mirror of
https://github.com/borgbackup/borg.git
synced 2024-12-24 08:45:13 +00:00
update development.rst for docs changes
This commit is contained in:
parent
95b69a433c
commit
847797b477
1 changed files with 24 additions and 12 deletions
|
@ -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
|
||||||
|
|
Loading…
Reference in a new issue