Port documentation to Sphinx #78
Description
We need your help to port the existing documentation from Markdown to reStructuredText so that we can publish it on ReadTheDocs!
The Markdown files are located here:
https://github.com/iotaledger/documentation/tree/iota.lib.py/1.2.x/source/includes
These need to be copied into the PyOTA repository and converted to reStructuredText here:
https://github.com/iotaledger/iota.lib.py/tree/develop/docs
Note: This is a big project, and multiple people might end up working on this. Please be sure to post here so that you can coordinate with others, to avoid duplicating work.
If you are not familiar with Sphinx and/or reStructuredText, here's a quickstart:
- Install PyOTA locally.
pip install sphinxcd docsmake html- This will generate the static HTML documentation. You can then open
docs/_build/html/index.htmlin your browser to see what it will (sort of) look like when it is published to RTD.
- This will generate the static HTML documentation. You can then open
- To make changes to the documentation, edit the corresponding
.rstfile, and then do anothermake html.
Important: If you add a new .rst file, be sure to update the toctree directive in index.rst!
Here are some references for reStructuredText directives and markup syntax (once you get used to it, you will never want to go back to Markdown 😸):
- http://docutils.sourceforge.net/docs/user/rst/quickref.html
- http://docutils.sourceforge.net/docs/ref/rst/directives.html
- http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
You can also use this online rst editor to try stuff out:
http://rst.ninjs.org/