This page explains how to make your first steps with Sphinx. We currently use docbook to generate man pages and user's guide. We hope to replace that with Sphinx.
How to start your Sphinx edits
- Make sure you have Sphinx installed on your system (see here http://www.sphinx-doc.org/en/master/usage/installation.html)
- get Kea sources on your laptop:
git clone firstname.lastname@example.org:isc-projects/kea.git
- checkout docbook-to-sphinx:
git checkout docbook-to-sphinx
autoreconf -i && ./configure --enable-generate-docsAm afraid you will have to get all the mandatory Kea dependencies for this.
Now you can:
make guide- this will generate a single HTML in _build/ directory.
make pages- this will generate a multi-page HTML doc in _build2/ directory.
make pdf- one day this will generate PDF version. I was not able to make it work on MacOS, because Sphinx requires latexmk and it's not easily installable on MacOS.
The documentation is kept in .rst files (restructured text). The files are in doc/guide/.
Gitlab basics (a quick refresher for people who don't contribute to Kea frequently)
If you do your changes via gitlab web interface, make sure you do
git pull on your laptop before regerenating.
If you do your changes on your laptop, make sure you commit and push your changes.
git gui is a great way to do that conveniently.
Need to review existing .rst files. This is something @godfryd converted automatically and then spent some time fixing more obvious issues. Please make sure the links look right and follow to the right places (for exmaple they show ??? now instead of something more useful). Check if tables look correct. Also, try to apply templates so the docs looks more similar to what BIND has.
Once the generation works reliably, remove docbook files, update makefiles.
Make sure the sphinx detection in configure script (--with-generate-docs) works properly. It's very basic now.