DCS Documentation Website¶
This section is aimed at potential authors of documentation, specifically, the contributers of the standard documentation associated with the developers to cover the details on how DCS documentation works.
It includes information about the markup language and formats, introducing the user to create a draft build that allows to viewing changes and validating before deploying.
Install Material for Documenting¶
The site generator employed for building DCS documentation website is a fast and simple site generator known as 'MkDocs'. For more information visit https://www.mkdocs.org/.
Documentation source files are written in a language known as 'Markdown' with the file extension .md and configured with a single YML configuration file. For more information visit https://squidfunk.github.io/mkdocs-material/ .
Recommended method of installation is to get material for MkDocs via the Python package manager pip, however the user might have to use one the other methods listed below if that is not possible.
pip install mkdocs-material
- Automatically install compatible versions of all dependencies:
- Material for MkDocs always strives to support the latest versions.
- Separate installation of packags is not required.
docker pull squidfunk/mkdocs-material
- The official Docker image comes with all dependencies pre-installed.
git clone https://github.com/squidfunk/mkdocs-material.git
- Method to use material directly from GitHub by cloning the repository into a subfolder of the project root.
pip install -e mkdocs-material
- If cloning from git, the user must install all required dependencies as they do not get installed automatically.
MkDocs installation must facilitate the installation of compatibale versions of following dependancies : MkDocs, Markdown, Pygments and Python Markdown Extensions.
Create the Site¶
Once Material for MkDocs are installed, project should be bootstrapped using the mkdocs executable.
If inside where the project should to be located : Enter mkdocs new .
If in a different directory : Provide the path and enter mkdocs new projectName
Incase of Unix, Powershell : Enter docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .
Incase of Windows : Enter docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material new .
If done successfully, user would be able to see the file structure created in the project.
Configure the Site¶
Basic configuration is done the mkdocs.yml document resides inside the main directory of the project.
Minimal Configuration
Follow the link for instructions : https://squidfunk.github.io/mkdocs-material/creating-your-site/#minimal-configuration
Advanced Configuration
Follow the link for instructions on advanced configuration : https://squidfunk.github.io/mkdocs-material/setup/
Follow the link for instructions on extension configuration : https://squidfunk.github.io/mkdocs-material/setup/extensions/
According to user requirements markdown files (.md extension) could be associated via mkdocs.yml document.
Build the Site¶
A static site from markdown files could be generated by the use of following command once editing is completed.
mkdocs build
The content of this directory make up project documentation without a database or a server, as it is completely self-contained.
The site can be hosted on GitHub Pages, GitLab Pages, a CDN of preference or in a private web space.
Preview the Site¶
Previewing changes in the process of editing could be done by the use of following command inside the main project directory.
mkdocs serve
The server will automatically rebuild the site upon saving after the command was first added.
Point the browser to localhost:8000 and the user would be able to see the site in an interface.