Gerbera uses Sphinx Python Document Generator to generate documentation.
Below you will find instructions on how to:
- Generate documentation
- View documentation
- Add to documentation
- Publish documentation
Install Python virtualenv using the pip virtualenv instructions
The Gerbera documentation uses a shell script to build the documentation with Sphinx.
$ chmod u+x ./do_sphinx.sh
$ ./do_sphinx.shTo clear an existing
_builddirectory
$ ./do_sphinx.sh --clobberThe script does the following activities:
- Creates a Python virtualenv under
doc/_build/gerbera-env - Installs Sphinx with Read-The-Docs theme
- Generates documentation using Sphinx
Output looks similar to below:
Example run using
macOS High Sierra
bash-3.2$ ./do_sphinx.sh --clobber
Removing _build directory
Creating Gerbera documentation build directory /development/gerbera/doc/_build
Creating Gerbera Python virtualenv
Using base prefix '/usr/local/Cellar/python3/3.6.4/Frameworks/Python.framework/Versions/3.6'
New python executable in /development/gerbera/doc/_build/gerbera-env/bin/python3.6
Also creating executable in /development/gerbera/doc/_build/gerbera-env/bin/python
Installing setuptools, pip, wheel...done.
Installing Sphinx document genertor with sphinx_rtd_theme theme
Collecting Sphinx
Using cached Sphinx-1.6.6-py2.py3-none-any.whl
Collecting sphinx_rtd_theme
Using cached sphinx_rtd_theme-0.2.4-py2.py3-none-any.whl
Collecting docutils>=0.11 (from Sphinx)
Using cached docutils-0.14-py3-none-any.whl
Collecting Jinja2>=2.3 (from Sphinx)
Using cached Jinja2-2.10-py2.py3-none-any.whl
Collecting Pygments>=2.0 (from Sphinx)
Using cached Pygments-2.2.0-py2.py3-none-any.whl
Collecting babel!=2.0,>=1.3 (from Sphinx)
Using cached Babel-2.5.3-py2.py3-none-any.whl
Collecting requests>=2.0.0 (from Sphinx)
Using cached requests-2.18.4-py2.py3-none-any.whl
Requirement already satisfied: setuptools in ./gerbera-env/lib/python3.6/site-packages (from Sphinx)
Collecting alabaster<0.8,>=0.7 (from Sphinx)
Using cached alabaster-0.7.10-py2.py3-none-any.whl
Collecting sphinxcontrib-websupport (from Sphinx)
Using cached sphinxcontrib_websupport-1.0.1-py2.py3-none-any.whl
Collecting imagesize (from Sphinx)
Using cached imagesize-0.7.1-py2.py3-none-any.whl
Collecting six>=1.5 (from Sphinx)
Using cached six-1.11.0-py2.py3-none-any.whl
Collecting snowballstemmer>=1.1 (from Sphinx)
Using cached snowballstemmer-1.2.1-py2.py3-none-any.whl
Collecting MarkupSafe>=0.23 (from Jinja2>=2.3->Sphinx)
Collecting pytz>=0a (from babel!=2.0,>=1.3->Sphinx)
Using cached pytz-2017.3-py2.py3-none-any.whl
Collecting idna<2.7,>=2.5 (from requests>=2.0.0->Sphinx)
Using cached idna-2.6-py2.py3-none-any.whl
Collecting chardet<3.1.0,>=3.0.2 (from requests>=2.0.0->Sphinx)
Using cached chardet-3.0.4-py2.py3-none-any.whl
Collecting certifi>=2017.4.17 (from requests>=2.0.0->Sphinx)
Using cached certifi-2018.1.18-py2.py3-none-any.whl
Collecting urllib3<1.23,>=1.21.1 (from requests>=2.0.0->Sphinx)
Using cached urllib3-1.22-py2.py3-none-any.whl
Installing collected packages: docutils, MarkupSafe, Jinja2, Pygments, pytz, babel, idna, chardet, certifi, urllib3,
requests, alabaster, sphinxcontrib-websupport, imagesize, six, snowballstemmer, Sphinx, sphinx-rtd-theme
Successfully installed Jinja2-2.10 MarkupSafe-1.0 Pygments-2.2.0 Sphinx-1.6.6 alabaster-0.7.10 babel-2.5.3
certifi-2018.1.18 chardet-3.0.4 docutils-0.14 idna-2.6 imagesize-0.7.1 pytz-2017.3 requests-2.18.4 six-1.11.0
snowballstemmer-1.2.1 sphinx-rtd-theme-0.2.4 sphinxcontrib-websupport-1.0.1 urllib3-1.22
Build Gerbera Documentation
Running Sphinx v1.6.6
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying static files... WARNING: html_static_path entry '/development/gerbera/doc/_static' does not exist
done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 1 warning.
SUCCESS generated Gerbera documentation:
/development/gerbera/doc/_build/dist
You can view the documentation by creating a static web server in Python.
$ source _build/gerbera-env/bin/activate
(gerbera-env) $Deactive the virtualenv using
deactivatecommand
(gerbera-env) $ cd _build/dist/
(gerbera-env) $ python -m http.server 8000Visit the generated documentation using the server URL in a browser
The Sphinx document generator uses reStructuredText to generate the doucmentation.
First, take a look at the Sphinx reStructuredText Primer
TODO: