We welcome anyone to contribute to the Cosine documentation. Below is a guide on how to best do so.
You will need:
- Python3 and Pip
- Git
Then:
- Clone this repo
git clone https://github.com/2pisoftware/cosine-docs.git - Install the python dependencies
python3 -m pip install -r requirements.txt - Preview the site locally
mkdocs serve
You should now be able to make changes to the documentation and see them rendered at https://127.0.0.1:8000
- Write content for the public. The scope of this site is specifically for information regarding the two Cosine repos cmfive-core and cmfive-boilerplate. Do not include information for content outside these, such as other 2piSoftware repositories.
- Write assuming knowledge of the language and problem domain. Do not include information such as common PHP syntax, for example control structures like for loops or if statements.
- Cosine is Cosine. Despite the repositories being named Cmfive, please use the name Cosine when writing here unless writing specifically about one of the two repos.
- Make content searchable. Make use of specific headings and language such that users can find content using the search bar. I.e. mention the components or problem specifically instead of as a general idea.
- Include examples. When talking about usage, it is better to show than tell. Include code blocks using best practices, and code comments to explain as you go.
This site currently has a number of mkdocs extensions enabled to allow for more versatile markdown syntax and rendering. Below is a list of the enabled extensions and their documentation.
- Mkdocs Material Admonitions
- Python Markdown Details
- Python Markdown Highlight
- Python Markdown InlineHilite
- Python Markdown Superfences
- Python Markdown Tabbed
Once you're done writing, make a commit containing your changes and push to a new branch or fork. Then, make a PR. It will be reviewed, changes requested if necessary, and merged into main.
Do not push directly onto main.