mirror of
https://gh.wpcy.net/https://github.com/WeblateOrg/weblate.git
synced 2026-04-25 01:22:24 +08:00
b3e8b859a0
- Use consistent ordering so that the content doesn't appear in random order when added. - Update contributor documentation to match the current flow. - Split add-ons docs to make it easier to generate. Fixes #18724
78 lines
3 KiB
ReStructuredText
78 lines
3 KiB
ReStructuredText
Contribute to Weblate documentation
|
||
===================================
|
||
|
||
You are welcome to improve the documentation page of your choice.
|
||
Do it easily by clicking the :guilabel:`Edit on GitHub` button in the top-right corner of the page.
|
||
|
||
Documentation guidelines
|
||
------------------------
|
||
|
||
Please respect these guidelines while writing:
|
||
|
||
1. Don’t remove part of the documentation if it’s valid.
|
||
2. Use clear and easily-understandable language. You are writing tech docs, not a poem.
|
||
Not all docs readers are native speakers, be thoughtful.
|
||
3. Don’t be afraid to ask if you are not certain.
|
||
If you have to ask about some feature while editing, don’t change its docs before you have the answer.
|
||
This means: You change or ask. Don’t do both at the same time.
|
||
4. Verify your changes by performing described actions while following the docs.
|
||
5. Send PR with changes in small chunks to make it easier and quicker to review and merge.
|
||
6. If you want to rewrite and change the structure of a big article, do it in two steps:
|
||
|
||
1. Rewrite
|
||
2. Once the rewrite is reviewed, polished, and merged, change the structure of the paragraphs in another PR.
|
||
|
||
Building the documentation locally
|
||
----------------------------------
|
||
|
||
Documentation can be also edited and built locally, the Python requirements are
|
||
in the ``docs`` dependency group in :file:`pyproject.toml`. If you already use
|
||
the full development environment, ``uv sync --all-extras --dev`` is enough. For
|
||
documentation work only, ``uv sync --group docs`` is sufficient.
|
||
|
||
The recommended local workflow is:
|
||
|
||
.. code-block:: sh
|
||
|
||
make -C docs update-docs
|
||
./ci/run-docs
|
||
|
||
The :program:`ci/run-docs` wrapper builds the documentation with warnings
|
||
treated as errors.
|
||
|
||
.. hint::
|
||
|
||
You will also need :program:`graphviz` installed to build the documentation.
|
||
|
||
Translating the documentation
|
||
-----------------------------
|
||
|
||
You can `translate the docs <https://hosted.weblate.org/projects/weblate/documentation/>`_.
|
||
|
||
Updating generated documentation snippets
|
||
-----------------------------------------
|
||
|
||
Several documentation sections use templates generated from the code. The
|
||
preferred way to refresh them is:
|
||
|
||
.. code-block:: sh
|
||
|
||
make -C docs update-docs
|
||
|
||
This target regenerates the snippets currently used by the documentation,
|
||
including:
|
||
|
||
* add-on events, built-in add-ons, and common add-on parameters
|
||
* machine translation services
|
||
* file format parameters and file format feature tables
|
||
* permissions and built-in roles
|
||
* checks and check flags
|
||
|
||
Keep manually maintained text in the parent documentation page rather than
|
||
adding it to autogenerated snippets. For example, :doc:`/admin/addons`
|
||
includes three generated files for events, built-in add-ons, and common add-on
|
||
parameters, while obsolete add-ons are maintained directly in the page.
|
||
|
||
If you need to regenerate only one part, the individual management commands are
|
||
documented in :doc:`/admin/management`, and the exact commands used by
|
||
``update-docs`` are listed in :file:`docs/Makefile`.
|
