documentation

[12rambau]

Fix #2065

description

As suggested in our email exchange, I built a fully functional documentation environment for your documentation. It is based on the Sphinx Python tool and fancy extensions. I didn't set anything related to the automatic build as I think that most of the work here will be done locally.

In this first draft you'll find:

• a docs/ folder with the build environment and some dummy sources
• the requirements.txt with the python libs used to create the theme
• some initial things like a "404 not found" custom page, the arena logo here and there, links (github, twitter, website), a demo structure and 2 pages that describe the available directives and roles
• 5 custom extention (btn, icon,youtube, notfound, image)
• everything is based on the pydata-sphinx-theme and can be customized further if you're interested

installation

Pull the branch on you local machine and create a python venv in the docs directory:

$ cd docs
$ python -m venv venv

This folder is already in the .gitignore.

Then install all the python packages in the venv:

$ source venv/bin/activate
(venv)$ pip install -r requirements.txt

You are now ready to build the documentation from the docs/ folder:

(venv)$ make html

or

(venv)$ make latexpdf

to get started

Of course, the objective here is to build the real documentation from what is existing in https://docs.google.com/document/d/1GWerrExvbdT5oOOlwdkE9pptK4pVbQxwtgaSNPasmKA/view. if you build the documentation, in docs/build/html/start/kitchen-sink.html you'll find more or less all the existing directives and in docs/build/html/start/custom.html some more custom information about the custom extension and a few coding guidelines.

I you're missing anything let me know !

🚀 Happy documenting

[sonarcloud]

SonarCloud Quality Gate failed.   

3 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

No Coverage information
0.0% Duplication