steemit / devportal

Steem Platform Developer Documentation.
https://developers.steem.io
MIT License
122 stars 74 forks source link

Autogenerate API docs #14

Closed GwenNelson closed 6 years ago

GwenNelson commented 6 years ago

All API docs should be autogenerated, we can use a tool like sphinx for the python code to generate documentation from docstrings automatically and then convert it to markdown using pandoc or similar.

I'd be happy to put together a script to do this conversion for the python codebase, i'm not familiar with similar tools for the javascript codebase though.

Longer term we probably want automatic documentation for the JSON-RPC API in steemd too - i'd be amazed if tools don't exist for doing this from a schema.

GwenNelson commented 6 years ago

In terms of implementation, basic idea here is to use the autodoc feature in sphinx, spit out a bunch of rst files and then process that into markdown using pandoc for integration into the developer portal.

The markdown files should probably live in the steem-python repo officially and then be pulled in as part of the build process in this repo.

originated commented 6 years ago

I've spoken to @mvandeberg for steemd and we can circle with him, he has some good suggestions to automate that. In terms of Python if you'd like to do that would be great being more familiar with Pydocs, etc as we do need to have the Python docs included directly on DevPortal.

GwenNelson commented 6 years ago

I believe we already have/had some sphinx docs in the repo - for the dev portal i'd suggest we only need a few simple examples and API reference, nothing too fancy.

relativityboy commented 6 years ago

Issue resolved in other stories.