|
|
This page explains how to make your first steps with [Sphinx](https://www.sphinx-doc.org/en/master/). 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
|
|
|
|
|
|
1. Make sure you have Sphinx installed on your system (see here http://www.sphinx-doc.org/en/master/usage/installation.html)
|
|
|
1. get Kea sources on your laptop: `git clone git@github.com:isc-projects/kea.git`
|
|
|
1. checkout docbook-to-sphinx: `git checkout docbook-to-sphinx`
|
|
|
1. autoreconf -i && ./configure --enable-generate-docs
|
|
|
1. cd doc
|
|
|
|
|
|
Now you can:
|
|
|
|
|
|
1. `make guide` - this will generate a single HTML in _build/ directory.
|
|
|
1. `make pages` - this will generate a multi-page HTML doc in _build2/ directory.
|
|
|
1. `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.
|
|
|
|
|
|
## Sphinx overview
|
|
|
|
|
|
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. |
|
|
\ No newline at end of file |