Pysyft: Set up API documentation generation

[samsontmr]

Now that our codebase is growing (hooray!), we can start thinking about setting up a pipeline to generate nice API docs for Data Scientists. Matplotlib has fantastic documentation, we could use them as inspiration

[cypherai]

Agreed 🙂 How about using sphinx or mkdocs?

[samsontmr]

Heard of sphinx but not mkdocs! Pros and cons? Something to consider as well would be whether it supports JS (we should try to use the same tools across components).

[cypherai]

I'm only familiar with mkdocs. I think it has only basic features compared to sphinx. However, some major projects use it to generate docs automatically.

I would suggest that we take a look at what Keras does with it:

• https://keras.io
• https://github.com/fchollet/keras/tree/master/docs

[samsontmr]

Wow! it looks pretty nice too

GitHub is wonky lol...pretty sure it was I who did that

[Edvac]

Sphinx is nice. I am using it to document my code. I like the autodocs (auto generated documentation from comments in the code). I think Sphinx is a nice choice because it is under active development. github repo and also it is used as well in big projects
examples. It has also some tutorials on youtube that can help.

[samsontmr]

@Edvac thanks for the input! I quite like the autodocs feature too :P

[cypherai]

I'm OK with Sphinx. It may be a more robust choice over time, and i'm ready to learn as well.

[Edvac]

I think so too. It seems more robust than other generators.
There are quite a few cool documentation generators like

• natural docs

• dexy

• doxygen

But they are not currently under development or as much as sphinx.
This site can give you an nice insight: javascript documentation .
(Although it is about javascript documentation it includes also general tools like sphinx.)

Sphinx seems to be one of the most used. That's why I decided to use it.
If anyone uses something else it would be nice to enlighten us. :-)

Also I think is good to have in mind what we want to document.
as you said @samsontmr " Set up API documentation generation"
Sphinx we could say is also a "General purpose open source documentation tool". While tools like

1. raml
2. swagger
3. apiblueprint

are suitable for only api documentation.

These are two nice thoughts about the types of documentation.

• stackoverflow

• Yevgeniy Brikman blog post

So I think, if the question is only for "Set up API documentation generation". Sphinx would be a wise choice but there are also tools that are focused specificaly on API documentation.

[nikonoll]

Random new guys opinion here:
As @Edvac already hinted at the subject of pure API documentation differs from just general doc generation. From personal experience I can only recommend swagger and it's UI - demo - since it can deliver a truly interactive API exploration experience and enforces correctness of documentation. It achieves this by actually having models for request/response (including data types, nested objects etc.) that can be tested from withing the documentation.

[nathanielcompton]

Has there been any movement on this issue? If not, I'll get to work.

[iamtrask]

Epic! Can't wait to see it!

[bharathgs]

@nathanielcompton any updates on this?