Implementation Details

How it works?

The VM used to generate the RTD site does the following:

1. A parallel hierarchy, by convention, is used with the readthedocs folder in Google Drive, and this project's Git root. In fact, the Vagrantfile maps the host's project root to the /readthedocs directory inside the VM that it creates. In the VM, you can change directory into /readthedocs to see all the project files there.
2. When provisioning (done the first time with a vagrant up or subsequently via vagrant provision), it pulls down Google Documents (word docx format/extension) recursively from a readthedocs folder hosted on the Google Drive.
3. After downloading them, these documents are converted into Markdown documents that the TOC in the index.rst file references for different sections of the RTD site.
4. Based on the file hierarchy convention, the TOC Tree in files referenced by the index.rst is generated by scripts. Other conventions may also be used besides file hierarchy but right now we think that hierarchy is best and should support our needs to convey enough information to the script to build the TOC Tree.
5. The script also integrates the Markdown from project wikis authored through GitHub Wikis. The Projects folder maps, as git submodules, project wiki Git repositories to make these Markdown documents accessible to the RTD site builder. The generated TOC files will have sections for these projects and their documents based on an embedded comment attribute called PARENT_PATH. This allows for docs like faqs, howtos, guides, etc to be organized even in the GitHub Wiki and included. The script even generates a sidebar for these GitHub Wiki repositories based on the hierarchy defined by PARENT_PATH.

What did you use?

Used word-to-markdown originally to convert Word documents in gdocs to Markdown, however we can lose information. Also finding that I can go straight to RestructureText with Pandoc without losing information in the Word Document. This might be the best route for dealing with gdocs. We might want to also abandon using CommonMark support in Sphinx and just translate Markdown into RestructureText letting Sphinx just use that instead.

Needed to handle project wiki markdown differently from exported Google Docs. Need to break conversion apart into two separate steps.

More to come this page is incomplete!