We are using MkDocs with the Material for MkDocs theme to build our documentation site. Some inspiration is taken from similar technical documentation sites of NERSC and Berkeley Research IT.
The repository has a requirements.txt file which can be used to install the required mkdocs, mkdocs-material, and other plugins required to build the documentation by executing:
pip install -r requirements.txt
mkdocs serve starts a live preview server for you to view on a browser window.
Since the MkDocs source files are text based, you can use your favorite editor. One recommendation is to use Visual Studio Code. An additional recommendation is to use the Material for MkDocs provided schema.json for mkdocs.yml; instructions can be found here.
Pushing changes to the github repository will automatically run mkdocs build and publish the generated html pages on github pages. These are hosted on the gh-pages branch while the markdown source of the documentation lies on the main branch.
This is achieved through Gihub Actions workflow file .github/workflows/ci.yml.