From d862a24a09652110e9ac3aead5a553e9681cf4b1 Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Tue, 5 Sep 2023 14:20:35 +0200 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=93=9A=20DOCS:=20Add=20outline=20of?= =?UTF-8?q?=20extension=20logic?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/contributing.rst | 61 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/docs/contributing.rst b/docs/contributing.rst index 4e6777650..f375d9bcf 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -184,3 +184,64 @@ to ``test.pypi.org`` and ``pypy.org``. .. Include our contributors and maintainers. .. include:: ../AUTHORS + + +Structure of the extension's logic +---------------------------------- + +The following is an outline of the build events which this extension adds to the Sphinx build process: + +#. After configuration has been initialised (``config-inited`` event): + + - Register additional directives, directive options and warnings (``load_config``) + - Check configuration consistency (``check_configuration``) + +#. Before reading changed documents (``env-before-read-docs`` event): + + - Initialise ``BuildEnvironment`` variables (``prepare_env``) + - Register services (``prepare_env``) + - Register functions (``prepare_env``) + - Initialise default extra options (``prepare_env``) + - Initialise extra link types (``prepare_env``) + - Ensure default configurations are set (``prepare_env``) + - Start process timing, if enabled (``prepare_env``) + - Load external needs (``load_external_needs``) + +#. For all removed and changed documents (``env-before-read-docs`` event): + + - Remove all cached need items that originate from the document (``purge_needs``) + +#. For changed documents (``doctree-read`` event, priority 880 of transforms) + + - Determine and add data on containing sections and parents to needs (``add_sections``) + +#. When building in parallel mode (``env-merge-info`` event), merge ``BuildEnvironment`` data (``merge_data``) + +#. After all documents have been read and transformed (``env-updated`` event) (NOTE these are skipped for ``needs`` builder) + + - Copy vendored JS libraries (with CSS) to build folder (``install_lib_static_files``) + - Generate permalink file (``install_permalink_file``) + - Copy vendored CSS files to build folder (``install_styles_static_files``) + +#. Note, the ``BuildEnvironment`` is cached at this point, only if any documents were updated. + +#. For all changed documents, or their dependants (``doctree-resolved``) + + - Replace all ```Needextract``` nodes with a list of the collected ``Need`` (``process_creator``) + - Remove all ``Need`` nodes, if ``needs_include_needs`` is ``True`` (``process_need_nodes``) + - Call dynamic functions, set as values on the need data items and replace them with their return values (``process_need_nodes -> resolve_dynamic_values``) + - Replace needs data variant values (``process_need_nodes -> resolve_variants_options``) + - Check for dead links (``process_need_nodes -> check_links``) + - Generate back links (``process_need_nodes -> create_back_links``) + - Process constraints, for each ``Need`` node (``process_need_nodes -> process_constraints``) + - Perform all modifications on need data items, due to ``Needextend`` nodes (``process_need_nodes -> process_needextend``) + - Format each ``Need`` node to give the desired visual output (``process_need_nodes -> print_need_nodes``) + - Process all need specific nodes, replacing them with the desired visual output (``process_creator``) + - Remove ``Need`` nodes marked as ``hidden`` (``remove_hidden_needs``) + +#. At the end of the build (``build-finished`` event) + + - Call all user defined need data checks, a.k.a warnings (``process_warnings``) + - Write the ``needs.json`` to the output folder (``build_needs_json``) + - Write all required UML files to the output file (``build_needumls_pumls``) + - Print process timing, if enabled (``process_timing``) From c47cb464d4511d019c83b862b78438f18e2f29ee Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Tue, 5 Sep 2023 14:28:07 +0200 Subject: [PATCH 2/3] Update contributing.rst --- docs/contributing.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index f375d9bcf..7864a32a1 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -182,10 +182,6 @@ The release jobs will build the source and wheel distribution and try to upload to ``test.pypi.org`` and ``pypy.org``. -.. Include our contributors and maintainers. -.. include:: ../AUTHORS - - Structure of the extension's logic ---------------------------------- @@ -245,3 +241,6 @@ The following is an outline of the build events which this extension adds to the - Write the ``needs.json`` to the output folder (``build_needs_json``) - Write all required UML files to the output file (``build_needumls_pumls``) - Print process timing, if enabled (``process_timing``) + +.. Include our contributors and maintainers. +.. include:: ../AUTHORS From 9372c518d176f72864313db1f18d17f2de3f4aee Mon Sep 17 00:00:00 2001 From: Chris Sewell Date: Tue, 5 Sep 2023 14:36:09 +0200 Subject: [PATCH 3/3] Update contributing.rst --- docs/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 7864a32a1..bbc709815 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -185,7 +185,7 @@ to ``test.pypi.org`` and ``pypy.org``. Structure of the extension's logic ---------------------------------- -The following is an outline of the build events which this extension adds to the Sphinx build process: +The following is an outline of the build events which this extension adds to the :ref:`Sphinx build process `: #. After configuration has been initialised (``config-inited`` event):