This repository contains the documentation website for AuroraX, found at https://docs.aurorax.space. The site has information about AuroraX and its data, the API, client libraries for Python and IDL, and more.
- Python 3.8+
This documentation repository contains pages discussing AuroraX, and also API reference documentation for supporting client libraries (ie. Python packages). To generate these API reference pages, we use "submodules" to link other repositories. Currently only PyAuroraX is linked as a submodule.
To generate documentation for submodules. they must first be initialized and their dependencies installed. You can either use a makefile target we have, or initialize the submodule manually.
-
Clone repository
$ git clone [email protected]:aurorax-space/docs.git -
Initialize submodules
$ git submodule update --init $ cd pyaurorax $ git checkout main $ git pull $ pip install poetry $ poetry install $ cd .. -
Submodules don't automatically update when changes are pushed to their upstream repositories, so updates must be pulled manually.
$ git submodule foreach git pull -
Install mkdocs dependencies
$ pip install -r requirements.txt -
Since the submodules in this repository are Python projects, their API references can be generated automatically using
pdoc3. This step generates HTML files and places them in the specified directory. The command to generate the docs is run through Poetry because the dependencies of the package were installed by Poetry in a virtual environment. This additional step ensures that each submodule maintains its own dependencies and that the documentation is generated for exactly the dependencies used by the submodule.$ cd pyaurorax $ poetry run python3 -m pdoc --html --force --output-dir ../docs/code/pyaurorax_api_reference pyaurorax --config "lunr_search={'fuzziness': 1}" -
Build and serve the website locally.
$ python3 -m mkdocs serve -
View the website at http://localhost:8000.
Deployment is done using the MkDocs gh-deploy command and is done manually. This command will build the docs, commit them to the "gh-pages" branch, and push this branch to GitHub. Please make sure to build and preview any changes locally first.
$ python3 -m mkdocs gh-deploy --force
Markdown files used to generate the documentation are located in the docs directory. Add or edit existing documents directly in this directory.
The navigation menu is generated from the structure provided in the mkdocs.yml file. To modify the navigation menu, modify this file and rebuild the docs.