bartlettroscoe
commented
3 years ago One example of a formatting problem with the Sphinx-generated documentation are bulleted lists like:
With DocUtils, this creates the nice bulleted list HTML shown here:
which shows:
But the Sphinx-generated HTML for that same RST text shown here:
which shows:
Hum, that actually looks fine now. It did not look fine when I reviewed this 18 days ago in https://github.com/TriBITSPub/TriBITS/issues/386#issuecomment-876597266.
So I am not sure what happened there. There was an error in the generation of the HTML due to a defect that I fixed in commit 1d66677c09fc82db9eace7c7e9fb99832dad76b7. Perhaps that fixed some of the formatting problems I was seeing? Would that not be funny if that was true.
Blocked by: #386
Blocking: #400
Description
Sphinx-generated forms of the TriBITS documentation was put together in #386 and is used to auto-deploy Sphix-generated forms of the TriBITS reStructuredText documents on the GitHub Pages site https://tribitspub.github.io/TriBITS/ that are created and deployed by the GitHub Actions workflow deploy_docs.yml. However, there are a few issues the Sphinx-generated documentation that need to be worked out before abandoning the DocUtils-generated HTML files which generated using a cron job that runs every 20 minutes on the Linux server that serves up the site tribits.org. As a result, the end state of #386 was to keep both forms of the documentation generation in place until we can prioritize addressing the lingering issues with the Sphinx-generated documentation. Once we can address these last few issues, then we can drop the DocUtils generation of these documents and fully embrace the Sphinx generation of these documents and take full advantage of the features of Sphinx and really improve these online documents.
Definition of Done
Do a full review of the Sphinx-generated documentation, comparing to the DocUtils-generated documentation.
Make the basic formatting of Sphinx-generated HTML work correctly (see list of known issues below).
Drop generation of DocUtils-generated documentation (after basic other issues addressed)
The links between the different Sphinx-generated documents are fixed to work between (after dropping support for DocUtils-generated files).
Ensure all links in all deployed documents are working.
List of known issues that need to be addressed
NOTE: Some of these issues could be fixed by the
sphinx_rst_generator.pyscript before completing the transition and the implementation of the solution may not be all that different except for small details.