...
This section highlights some of the syntax, capabilities and limitations of the ReadtheDocs structure. This is salient because the documentation of various Hyperledger projects relies on the ReadtheDocs platform.
ReadtheDocs Highlights:
- Hyperledger documentation on ReadtheDocs is populated by files from the various Hyperledger project GitHub pages
- Those GitHub pages are synced with the ReadtheDocs platform and Pull Requests sync up to an index.rst file
- The index.rst file, as the extension might imply, is built upon Sphinx and reStructured syntax. (RST stands for reStructured)
- Sphinx and reStructured have their own syntax, formatting and are designed specifically for formatting documentation
ReStructured Text:
- reStructured is not a full fledged markdown language, but does allow for some customization
- Myriad options for text formatting is available
- images and images with hyperlinks are available
- various themes are available
- backgrounds for code snippets like dark mode are available
- plug-ins for custom CSS and JS are available
- Tables, References / Bibliographic citations and a Table of Contents are available
RST Example from Hyperledger Fabric:
Sphinx
Sphinx allows for customization of themes, they can be found here. Should they be standard for all projects?
Proof of Concept for ReadMe:
A POC was performed for ReadtheDocs using the tutorial found here. Was to ensure that certain features that are in the web3 community may be applicable to Hyperledger projects. It was found that features are available but ReadtheDocs relies on third-party plug ins and that deeper / more web3-style layouts would require customization work.