Organicity Technical Documentation
This documentation is available here https://organicityeu.github.io/
This repository contains the source documentation in markdown. We use MkDocs to create the final webpage.
Feel free to contribute by adding new tutorials and resources. Simply fork the repository and use pull requests to contribute the new content.
How to edit the documentation
Clone the repository
git clone https://github.com/OrganicityEu/organicityeu.github.io.git
You will see the default branch is
mkdocs instead of
master is where the final html files will be created.
mkdocs package using pip:
pip install mkdocs
If you do not have Python or Pip installed check the MkDocs documentation
There's a single configuration file named
mkdocs.yml, and a folder named
docs that will contain your documentation source files.
After addinf a new page in the
docs folder you will need to edit the index at
pages: - home: index.md - new section: - new page name: newpagefile.md
MkDocs comes with a built-in dev-server that lets you preview your documentation
as you work on it. Make sure you're in the same directory as the
configuration file, and then start the server by running the
$ mkdocs serve INFO - Building documentation... INFO - Cleaning site directory [I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000 [I 160402 15:50:43 handlers:58] Start watching changes [I 160402 15:50:43 handlers:60] Start detecting changes
mkdocs branch of the git repository run the following command:
mkdocs gh-deploy --remote-branch master
That's it! Behind the scenes, MkDocs will build your docs and use the ghp-import tool to commit them to the master branch and push the master branch to GitHub.
We use the master branch since we are using a Github personal page. For other repositories you can use the gh-pages branch
Be aware that you will not be able to review the built site before it is pushed
to GitHub. Therefore, you may want to verify any changes you make to the docs
beforehand by using the
serve commands and reviewing the built
You should never edit files in the
master branch by hand always edit them on the
mkdocs branch and then deploy them using mkdocs.
API documentation and swagger
/api documentation is maintained at OrganicityEu-Platform/api. Follow the instructions there to generate the html files and copy them to
Other files generated outside MkDocs as the
/example/foo.html files can be added on:
docs/ index.md example/ foo.html
This work is licensed under a Creative Commons Attribution 4.0 International License.