Plan for improving Junction's documentation

[pradyunsg]

I figured it'll be a good idea to have a central location to discuss about the documentation updates I have planned for the project. The general overview is:

• Get a basic skeleton of sphinx documentation generation into the source tree.
  • Include the documents from current documentation (and mark them as old)
• Add "development" section with a "getting started" page
• Include relevant pages in the generated documentation, with the sources outside the documentation tree (uses the .. include ReST directive)
  • Contributing Guide
  • Code of Conduct
  • more?
• Make the API documentation clearer and more extensive
• Add a section for discussing the various functionalities of Junction
  • Step-by-step instructions to do common tasks
  • Provide overview of the UI

The plan is to use Sphinx and ReST for the documentation. I'll add support for Markdown documents to the Sphinx documentation but I won't be writing any new documentation using Markdown.

Feedback is welcome on this plan.

[pradyunsg]

#577 is the first step, covering the first 2 top level bullet points above.

[zerothabhishek]

@pradyunsg how/where do we publish the docs ? Does Github run a build for Sphinx docs too ?

Also, we need some documentation on how to use the software itself. Many parts are counter-intuitive, a few things that I could only learn by looking at the code. Can that also be considered within the scope of this ticket ?

[pradyunsg]

Does Github run a build for Sphinx docs too?

You can read rest files rendered locally, though they won't be rendered like sphinx. I'll setup a build on https://readthedocs.org/ :)

Can that also be considered within the scope of this ticket?

Yeps. That makes sense to me. :)