Documentation Overview
This directory contains the higher-level documentation for the Magma project.
The documentation is structured as a series of READMEs, which are then organized into a Docusaurus site for easy consumption.
About
Docusaurus
Docusaurus is a framework for static site generation, focusing on documentation-based sites.
The sidebars.json
and siteConfig.js
are the main entrypoints for updating our documentation site. The former determines which README docs are displayed, and the latter sets site-wide config values.
There are two categories of documentation: "current" and "versioned". The current docs are stored under docs/readmes/
. When cutting a specific release, we also capture a snapshot of the current docs and store them as versioned docs under docs/docusaurus/versioned_docs/
. The sidebars are similarly versioned, with the versioned sidebars stored under docs/docusaurus/versioned_sidebars
.
Conventions
Follow the existing conventions when naming and placing new READMEs. Notably,
- Use short, concise verbs as section and document titles (e.g. "Upgrade", "Deploy", "Debug")
- Guide names and format should match across Magma components (i.e. Orc8r's "Upgrade to v1.4" and AGW's "Upgrade to v1.4" should flow together logically)
- A document's ID should match its filename
Some examples of proper naming
- Upgrade guide (upgrade to v1.4)
- Title:
Upgrade to v1.4
- ID:
upgrade_1_4
- Filename:
lte/upgrade_1_4.md
,orc8r/upgrade_1_4.md
- Title:
- Deploy guide (install)
- Title:
Install Orchestrator
,Install Access Gateway
- ID:
deploy_install
- Filename:
lte/deploy_install.md
,orc8r/deploy_install.md
- Title:
Howto
Make changes
- Add a doc: add the doc to the appropriate path under
docs/readmes/
, then updatesidebars.json
to include the added doc - Update a current doc: edit the relevant doc under
docs/readmes/
- Update a versioned doc: first update the corresponding current doc, then edit the relevant doc under
docs/docusaurus/versioned_docs
Precommit
Before pushing, verify your Markdown passes the linter. This is enforced by the markdown-lint
CI check. See Markdownlint rules and Magma's Markdownlint config for more info
# Check if changes pass Markdown lints
cd ${MAGMA_ROOT}/docs && make precommit
# Automatically fix some of the lints
cd ${MAGMA_ROOT}/docs && make precommit_fix
View local changes
Generate and run a local server serving your changes
cd ${MAGMA_ROOT}/docs && make dev
Cut Docusaurus versioned docs
If you want to cut a new versioned documentation release, bring up the Docusaurus container
cd ${MAGMA_ROOT}/docs/docusaurus
docker-compose down
docker build --tag magma_docusaurus .
docker-compose -f docker-compose.yml -f docker-compose.publish.yml up --detach
docker-compose exec docusaurus bash
From inside the container, build the site
yarn install
yarn build
Now you can create a new versioned release
yarn run version X.Y.0 # e.g. version 1.5.0
Commit all the new generated files and tweak the sidebars if you need to. Run make dev
to preview your changes.