diff options
| author | Dennis Oberst <dennis.oberst@qt.io> | 2023-10-24 13:46:00 +0200 |
|---|---|---|
| committer | Dennis Oberst <dennis.oberst@qt.io> | 2023-10-26 13:56:42 +0200 |
| commit | 92b9a8807c33120e6347a82a6ab65dc8828dec0e (patch) | |
| tree | 2bfe830727b8e69ea5c7544d44e3a1e9674c93b9 /sources/pyside6/doc/gettingstarted | |
| parent | 9205a48848c881c67130e7b96e3ad98aa870052e (diff) | |
docs: deprecate 'build_rst_docs' in favor of 'build_base_docs'
The command for building documentation files has been renamed to
'build_base_docs' and the previous command, 'build_rst_docs', has been
deprecated. All relevant occurrences of the command have been updated
accordingly. In addition, the documentation config and build directory
'build/pyside6/doc/rst' has been renamed to 'build/pyside6/doc/base'.
To ensure a fresh start when generating new documentation, the
auto-generated `examples` and `html` directories are now deleted
before generating new documentation. This change has been made
because these directories are generated anyway, and starting fresh
ensures that there are no conflicts or issues with the new
documentation.
Task-number: PYSIDE-2504
Change-Id: I395ad7e9482b0b68311820d58da362513ebb44b2
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
Diffstat (limited to 'sources/pyside6/doc/gettingstarted')
| -rw-r--r-- | sources/pyside6/doc/gettingstarted/index.rst | 26 |
1 files changed, 14 insertions, 12 deletions
diff --git a/sources/pyside6/doc/gettingstarted/index.rst b/sources/pyside6/doc/gettingstarted/index.rst index b7b956a40..f57b39378 100644 --- a/sources/pyside6/doc/gettingstarted/index.rst +++ b/sources/pyside6/doc/gettingstarted/index.rst @@ -416,16 +416,17 @@ You can find the ``requirements-doc.txt`` file in the root of the repository. Starting from 5.15, there are two options to build the documentation: -1. Building rst-only documentation (no API) +1. Building the base documentation (no API) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The process of parsing Qt headers to generate the PySide API documentation can take several -minutes, this means that modifying a specific section of the rst files we currently have, might -become a hard task. You may only care about the ReStructuredText only documentation. +minutes, this means that modifying a specific section of the documentation we currently have, might +become a hard task. You may only care about the base documentation, which comprises all the +documentation except for the API documentation. To generate this, execute the following command:: - python setup.py build_rst_docs + python setup.py build_base_docs This will generate an ``html/`` directory with the following structure:: @@ -443,13 +444,14 @@ files. This is useful when updating the general sections of the documentation, adding tutorials, modifying the build instructions, and more. -.. note:: In case you are interested in generating the Example Gallery, you - would need to first run ``python tools/example_gallery/main.py`` to - generate the examples ``rst`` for the gallery. +.. note:: In case you are interested in only generating the Example Gallery, + you would need to run ``python tools/example_gallery/main.py`` to + generate the examples ``documentation`` for the gallery. This will + also be used internally by the ``build_base_docs`` target -2. Building the documentation (rst + API) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +2. Building the documentation (Base + API) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The documentation is being generated using **qdoc** to get the API information, and also **sphinx** for the local Python related notes. @@ -486,7 +488,7 @@ The target executes several steps: Re-running the command will not execute step 1 unless the file ``qdoc-output/webxml/qtcore-index.webxml`` is removed from the build tree. -Similarly, step 2 will not be executed unless the file ``rst/PySide6/QtCore/index.rst`` +Similarly, step 2 will not be executed unless the file ``base/PySide6/QtCore/index.rst`` is removed. Finally, you will get a ``html`` directory containing all the generated documentation. The offline @@ -496,7 +498,7 @@ can find ``Shiboken.qch`` in the build directory, ``build/<your_env_name>/build/ If you want to temporarily change a ``.rst`` file to examine the impact on formatting, you can re-run ``sphinx`` in the ``doc`` directory:: - sphinx-build rst html + sphinx-build base html Viewing offline documentation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -519,7 +521,7 @@ Shiboken documentation. This can fail if * the default ``QCH`` format is used; in which case the required ``objects.inv`` files are not generated. Use ``--doc-build-online``. -* rst-only and full doc builds are mixed, resulting in wrong values for the +* base and full doc builds are mixed, resulting in wrong values for the intersphinx location in the CMake files. Re-run ``cmake`` to fix this. Using the internal tools |