This project contains the auto-phylo manual.
Before building the documentation, check the source/conf.py file to make sure that the auto-phylo version is right.
You need sphinx installed to generate the documentation. You also need to install the ReadTheDocs theme:
pip install -U sphinx
pip install sphinx_rtd_themePlaced in this directory, run make html. Documentation will be generated in ./build/html directory.
In order to generate de whole PDF, run make latexpdf. You will need the latexmk package. Documentation will be generated in ./build/latex.
In case of having problems of missing dependencies of latex packages, try installing these packages: texlive-fonts-recommended, texlive-latex-recommended, and texlive-latex-extra.
The documentation source files are located at the ./source directory.
Documentation is written using reStructuredText. In the following links you can find information about the syntax:
- http://docutils.sourceforge.net/docs/user/rst/quickref.html
- http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
You can use two extensions to edit and see live previews, but not both:
-
Esbonio extension, to manage the Esbonio server, who is able to build and serve sphinx projects. The
.vscode/settings.jsonis configured to make Esbonio build its results into_build, avoiding conflicts with thebuildfolder, which is generated duringmake html. -
RestructuredText extension, which also integrates with the Esbonio server, as the previous. Read the prerequisites as you may need to install
esbonioas well.
None of both are perfect by now. The Esbonio extension generates a working preview (links work, but there is no vertical scroll sync), but lacks some functionalities when editing that the RestructuredText extension provides. However, we detect bugs in the latter, such as links not working properly in live preview.
Moreover, from our experience, you will need Python 3.8 or greater in order the Live preview to work without errors.