Build TriBITS Documentation with Sphinx and deploy to the web

[bartlettroscoe]

CC: @marcinwrobel1986, @fnrizzi

Description

As discussed at the prior meeting on 6/24/2021, this Issue is to investigate the building and rendering of TriBITS documentation written in reStructuredText using Sphinx and deploy somehow to the web.

There are three documents that are generated using as reStructuredText files using the script:

$ cd TriBITS/
$ cd tribits/doc/
$ ./build_docs.sh

All the details of what gets built and how can be found in that script and the scripts and tools it calls.

To build the documentation locally, one needs to have docutils installed. But even without docutils installed, these scripts will still build everything needed to for the assembled files:

tribits/doc/guides/maintainers_guide/TribitsMaintainersGuide.rst
tribits/doc/guides/users_guide/TribitsUsersGuide.rst
tribits/doc/build_ref/TribitsBuildReference.rst

The script:

tribits/doc/publish_docs.sh

is used to publish the generated *html files on the tribits.org site (but you can run it locally to test it out).

Tasks

• Implement sphinx build of the documents ... See PR Build and deploy TriBITS documentation with Sphinx (#386) #387
• Deploy sphinx documents as a GitHub pages site ... See the site https://tribitspub.github.io/TriBITS/ served off of of the branch https://github.com/TriBITSPub/TriBITS/tree/deploy-doc-site
• Update tribits.org to point to new site and new in-progress Sphinx-generated documents
• Create follow-on GitHub Issue listing remaining issues that need to be resolved before abandoning the DocUtils-generated documentation and fully adopting the Sphinx-generated documentation.

[bartlettroscoe]

CC: @fnrizzi, @keitat

@marcinwrobel1986, as we discussed at last Thursday's meeting, this is the issue to investigate using Sphinx and readthedocs.com to improve the rendering of the TriBITS documentation currently hosted at tribits.org.

[bartlettroscoe]

After merging #387, in this github repo's "Pages" settings, I sest:

and now you can see this site deployed at:

• http://tribitspub.github.io/TriBITS/

and the three documents are displayed there. Nice!

[bartlettroscoe]

I updated the old tribits.org site to also point to the new Sphinx-generated HTML documents.

Lastly, I will post a GitHub Issue for the remaining issues for the Sphinx-generated documentation before we can switch over and abandon the DocUtils-generated documentation.

[bartlettroscoe]

CC: @marcinwrobel1986

To follow on from this, I created #399 to address what needs to be done to drop the DocUtils-generated documents and fully transition over to Sphinx with no regressions. I also I created the follow-on issue #400 for taking full advantage of Sphinx after this transition to make these proper Sphinx/ReadTheDocs documents as people would expect.

NOTE: As part of the writing of #399 and a little more investigation, it seems that the formatting problems I am seeing with the Sphinx-generated documents is due to a problem with the sphinx and/or sphinx-rtd-theme installation on my SNL RHEL 7 machine (installed with pip3 install --local sphinx sphinx-rtd-theme). When the Sphinx documentation is built with the GitHub Actions job, the formatting problem I saw is gone. The problem was also gone when built using a sphinx and sphinx-rtd-theme installation on my Windows 10 laptop under Cygwin (using a Frankenstein setup mixing software installed for Cygwin and native Windows which is a miracle). (It is issues like this why I gave up on Sphinx years ago when I tried. It is just so time consuming fighting issues like this with complex software.)

I will now close this Issue and move on with the hard technical tasks in EPIC #367 where time is running out this FY. Hopefully there will be time and $$ in FY22 to complete #399 and #400 and complete this transition to the Sphinx.

Thanks for all of your hard work on this! What we have in place is pretty nice. (Just a bit more work and I think we would be completely done.)

[marcinwrobel1986]

Thank you Ross! I keep my fingers crossed for complete transition!