Overview of Project Athena's Documentation Tools
For Project Athena's main documentation system, we use Sphinx to generate it, and Read the Docs to publish/host it. GitHub is a helpful middleman and stores all of the docs.
Sphinx is an open-source, robust solution for software documentation that includes features that writers expect, like:
- Single Source Publishing (HTML, PDF, ePub, and more)
- Content reuse through includes
- Multiple mature HTML themes that provide great user experience on mobile and desktop
- Referencing across pages, documents, and projects
- Index and Glossary support
- Localization support
Read the Docs is a hosting platform for Sphinx-generated documentation. It takes the power of Sphinx and adds version control, full-text search, and other useful features. It pulls down code and doc files from Git then builds and hosts the documentation.
Our main documentation is hosted at https://docs.projectathena.dev.
Install Sphinx for Local Builds
We encourage you to compile the documentation locally on your computer prior to submitting a PR. To install Sphinx:
Run cmd as administrator.
Install Chocolatey via the cmd (on one line):
@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"
Install Python 3 via Chocolatey via the cmd:
C:\> choco install python
Restart cmd or refresh with the command:
Install Sphinx in a command line:
C:\> pip install -U sphinx
Install the Markdown parser recommonmark:
C:\> pip install --upgrade recommonmark
Install our Sphinx theme:
C:\> pip install sphinx_rtd_theme
Compile Athena Documentation Locally
- Fork and clone https://github.com/kasenvr/athena-docs-sphinx.
- Using a command line, cd to your local repository, then the docs folder.
- Compile with the command
The HTML output will be in build\html. Open index.html in a browser to view docs.
Most of our docs use RST. reStructuredText (RST) is the default plaintext markup language used by Sphinx. It is an extensible markup language, that is fully customizable. However, we don't (yet) have need of this, and will stick with the default set of directives for High Fidelity's documentation. To learn more, refer to Sphinx's reStructuredText Primer.