mirror/borg
1
0
Fork 0
mirror of https://github.com/borgbackup/borg.git synced 2024-12-25 01:06:50 +00:00
Code Issues Releases Wiki Activity

update development.rst for docs changes

Browse source
This commit is contained in:
Marian Beermann 2017-02-11 16:01:26 +01:00
parent 95b69a433c
commit 847797b477
1 changed files with 24 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
docs/development.rst
View file

@ -141,25 +141,36 @@ Important notes:
- When using ``--`` to give options to py.test, you MUST also give ``borg.testsuite[.module]``. - When using ``--`` to give options to py.test, you MUST also give ``borg.testsuite[.module]``.
Regenerate usage files Documentation
---------------------- -------------
Usage and API documentation is currently committed directly to git, Generated files
although those files are generated automatically from the source ~~~~~~~~~~~~~~~
tree.
When a new module is added, the ``docs/api.rst`` file needs to be Usage documentation (found in ``docs/usage/``) and man pages
regenerated:: (``docs/man/``) are generated automatically from the command line
parsers declared in the program and their documentation, which is
./setup.py build_api embedded in the program (see archiver.py). These are committed to git
for easier use by packagers downstream.
When a command is added, a commandline flag changed, added or removed, When a command is added, a commandline flag changed, added or removed,
the usage docs need to be rebuilt as well:: the usage docs need to be rebuilt as well::
./setup.py build_usage python setup.py build_usage
python setup.py build_man
However, we prefer to do this as part of our :ref:`releasing`
preparations, so it is generally not necessary to update these when
submitting patches that change something about the command line.
The code documentation (which is currently not part of the released
docs) also uses a generated file (``docs/api.rst``), that needs to be
updated when a module is added or removed::
python setup.py build_api
Building the docs with Sphinx Building the docs with Sphinx
----------------------------- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The documentation (in reStructuredText format, .rst) is in docs/. The documentation (in reStructuredText format, .rst) is in docs/.
@ -230,6 +241,7 @@ therefore we recommend to use these merge parameters::
git merge 1.0-maint -s recursive -X rename-threshold=20% git merge 1.0-maint -s recursive -X rename-threshold=20%
.. _releasing:
Creating a new release Creating a new release
---------------------- ----------------------
@ -243,7 +255,7 @@ Checklist:
- update ``CHANGES.rst``, based on ``git log $PREVIOUS_RELEASE..`` - update ``CHANGES.rst``, based on ``git log $PREVIOUS_RELEASE..``
- check version number of upcoming release in ``CHANGES.rst`` - check version number of upcoming release in ``CHANGES.rst``
- verify that ``MANIFEST.in`` and ``setup.py`` are complete - verify that ``MANIFEST.in`` and ``setup.py`` are complete
- ``python setup.py build_api ; python setup.py build_usage`` and commit - ``python setup.py build_api ; python setup.py build_usage ; python setup.py build_man`` and commit
- tag the release:: - tag the release::
git tag -s -m "tagged/signed release X.Y.Z" X.Y.Z git tag -s -m "tagged/signed release X.Y.Z" X.Y.Z