Xud: Slate Documentation

[kilrau]

https://github.com/lord/slate

[kilrau]

Ok for you to take over? @ImmanuelSegol

[ImmanuelSegol]

Ok for you to take over? @ImmanuelSegol

@kilrau Yeah I will take care of this.
@sangaman We should talk about how to go about doing this.

[sangaman]

Basically, what I started on is writing a script that will take a proto file like ours and convert it to markdown syntax. Then we just have to check that in to the https://github.com/ExchangeUnion/slate fork I created and deploy it. I was also thinking of eventually putting code examples directly into the proto file comments, and parsing those into the code examples for slate documentation.

I couldn't find any generic tool we could use that does a good job of converting a proto file and its comments to slate. If you have another idea let me know.

[kilrau]

If you feel you won't have time for this til 31st, you can as @reliveyy if he's interested @ImmanuelSegol

[sangaman]

I'm putting the results of my work in progress here: https://exchangeunion.github.io/slate

[kilrau]

Looks really nice! So what is missing imo to finalize this

• examples
• search function
• logo
• link it in xud readme, wiki, exchangeunion.com

Anything else I'm missing?

PS: I assume you still generate the slate doc manually (which is fine for now) ? Any not-crazy-complicated way to automate this via travis on merge into master?

Also, I assume it's common practice to have the slate doc based on latest master (at least I couldn't find any versioning on e.g. https://api.lightning.community/). Just asking because https://readthedocs.org/projects/raiden-network/ has versioning.

[sangaman]

Yes the main work left is examples, I'm shooting for javascript & python at least to start. I expect to have that done today.

I'm going to open a PR in this repo as well to add a script to generate the slate markdown. I was actually thinking of tying it into the npm version script and only updating the published slate API docs on releases only, not on every merge to master. I believe that's how lnd does it, and it seems like a simpler way of going about it.

[kilrau]

tying it into the npm version script and only updating the published slate API docs on releases only, not on every merge to master. I believe that's how lnd does it, and it seems like a simpler way of going about it.

Didn't think about that option, but yes sounds like a good idea! Also basically answers my question about versioning - always be the latest release. If lnd does it that way - let's go for it.

[kilrau]

Great work! @sangaman

Quick feedback to the slate doc:

• Can we capitalize "XUD" in page title and in-text mentions? When it's a reference to an xud instance, as xud. Just like on https://api.lightning.community/. I know, gotta correct that in a lot of other places too.
• Intro: "Welcome to the gRPC API documentation for XUD, the Exchange Union Daemon. XUD is the client to access the Exchange Union network, a decentralized exchange built on the Lightning and Raiden networks connecting cryptocurrency exchanges. It enables instant and trustless cryptocurrency swaps and order fulfillment between exchanges. Exchanges participating in the network aggregate their liquidity and can provide deeper order books and new trading pairs to their users."
• And maybe use this favicon
  favicon_io.zip, the one you use currently is from the old design
• Can you host slate at something like exchangeunionslate.github.io? exchangeunion.github.io contains our old website as archive which I want to keep and I can't point a CNAME record to the subsite /slate. Or any other idea?
• If not already the case, can you also include the typedoc generation into the npm script?
• typedoc would also have to go to sth like exchangeuniontypedoc.github.io in order for me to point to it properly.

[sangaman]

I actually thought we'd agreed on lower case "xud" style, which I prefer. And fwiw it actually seems like the all caps usage of "LND" in their api docs is unusual, I don't see it that way anywhere else. The current slate doc is using PascalCase a few places in the description because that's the style for Service definitions in protobuf. I can change that, though, just need to make sure how.

For the favicon, I think it's pulling it from the ExchangeUnion organization settings in GitHub. That's not actually something that I'm setting or providing.

I'll get back with you about the domain/CNAME issues.

[kilrau]

"xud" style, which I prefer

Alright, not important anyways.

ExchangeUnion organization settings in GitHub

Interesting. No idea where it comes from then. But also not important.

I'll get back with you about the domain/CNAME issues.

That would be important ;)

[kilrau]

Slate: api.exchangeunion.com
Typedoc: typedoc.exchangeunion.com
Old website archive: exchangeunion.github.io