From 951121e1b06e760c5dcd71938457d08e70a03a2c Mon Sep 17 00:00:00 2001 From: Lina Wolf <48202465+linawolf@users.noreply.github.com> Date: Sat, 13 Jan 2024 19:22:43 +0100 Subject: [PATCH] [TASK] Adjust rendering page (#347) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [TASK] Adjust rendering page Releases: draft * Update Documentation/RenderingDocs/Index.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * Update Documentation/RenderingDocs/Index.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * [TASK] Apply suggestions from code review * Update Documentation/RenderingDocs/Index.rst Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> * [TASK] Apply suggestions from code review --------- Co-authored-by: Chris Müller <2566282+brotkrueml@users.noreply.github.com> --- Documentation/RenderingDocs/Index.rst | 135 +++++++------ .../RenderingDocs/Troubleshooting.rst | 189 ------------------ 2 files changed, 77 insertions(+), 247 deletions(-) delete mode 100644 Documentation/RenderingDocs/Troubleshooting.rst diff --git a/Documentation/RenderingDocs/Index.rst b/Documentation/RenderingDocs/Index.rst index 3e45d649..45e72a26 100644 --- a/Documentation/RenderingDocs/Index.rst +++ b/Documentation/RenderingDocs/Index.rst @@ -10,97 +10,116 @@ .. _render-documenation-with-docker: .. _render-documentation-with-docker: +========================================= +Render documentation with the TYPO3 theme +========================================= -=========================== -How to render documentation -=========================== +.. contents:: -This page explains how to render a manual locally on your machine -with Docker in order to test the rendering. +Rendering the :file:`Documentation` folder locally with Docker +============================================================== -Run these commands in a terminal in the parent directory of the directory -:file:`Documentation`. You should use a bash compatible shell, if possible. +You can render the documentation of an official TYPO3 manual or a third-party +manual with the following steps: -If you run into a problem while rendering, check :ref:`rendering-docs-troubleshooting`, -`report an issue `__ -or :ref:`ask for help `. +#. Clone the repository containing the documentation. +#. Navigate to the extension's root folder, the directory which contains the + :file:`composer.json`. -.. rst-class:: bignums-xxl +#. Check if there is documentation to be rendered: - #. Install Docker: https://docs.docker.com/install/ + A folder called :file:`Documentation` containing at least the files + :file:`Index.rst` and :file:`guides.xml`. - #. Preparations +#. Choose your prefered method of rendering (See below): - The docker image is not listed on Docker Hub (hub.docker.com) anymore, therefore some preparations - need to be done once: +Make sure that `Docker `__ is installed on your system. - .. code-block:: bash +.. tabs:: - # pull 'latest' version from GitHub container repository - docker pull ghcr.io/t3docs/render-documentation + .. group-tab:: Linux - # The "real" tag is independent of the container repository, - # so let's just create that extra "real" and "generic" tag - docker tag ghcr.io/t3docs/render-documentation t3docs/render-documentation + .. code-block:: bash - # verify it worked - docker run --rm t3docs/render-documentation --version + mkdir -p Documentation-GENERATED-temp + docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation + xdg-open "Documentation-GENERATED-temp/Index.html" - #. Make 'dockrun_t3rd' available in current terminal + .. group-tab:: MacOS - .. code-block:: bash + .. code-block:: bash - eval "$(docker run --rm t3docs/render-documentation show-shell-commands)" + mkdir -p Documentation-GENERATED-temp + docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation + open "Documentation-GENERATED-temp/Index.html" - This will run the Docker container and print out shell code. Once "eval-uated" - the code defines a helper function named `dockrun_t3rd`. This function relieves - you of the work of setting the volumes and rights correctly when running the - container and ensures a folder for the rendering results is provided. Executing - the code with `eval` defines the function for your current terminal. Don't forget - the quotes around everything that goes into eval. Either define the function each - time you open a new terminal window or add the line to the startup file of your - shell like `~/.bashrc` or `.zshrc`. + .. group-tab:: Windows - #. Run dockrun_t3rd + .. code-block:: powershell - .. code-block:: bash + New-Item -ItemType Directory -Force -Path ".\Documentation-GENERATED-temp" + docker run --rm --pull always -v ${PWD}:/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation + start "Documentation-GENERATED-temp/Index.html" - dockrun_t3rd makehtml +Publishing extension documentation to docs.typo3.org +==================================================== - This will automatically find the documentation in the - :file:`Documentation` subfolder. It will create a directory - :file:`Documentation-GENERATED-temp` and write the results there. +For your documentation to be published to https://docs.typo3.org, your +TYPO3 extension has to have a valid :file:`composer.json` and either a folder +called :file:`Documentation` with a :file:`Documentation/Index.rst` and +a :file:`Documentation/guides.xml` or a :file:`README.rst` / :file:`README.md` +in the extensions root directory. - #. Open generated documentation +The extension has to be publicly available on GitHub or GitLab. You have to +establish a :ref:`Webhook ` and the Documentation Team has to +:ref:`approve ` your first rendering. - Look at the output of the previous command to see where the - generated documentation is located or use one of these commands - to directly open the start page in a browser: +Introduce automatic testing for extension documentation +======================================================= - .. tabs:: +It is recommended to make sure your documentation always renders without +warning. On GitHub or GitLab you can introduce actions that test your +documentation automatically: - .. group-tab:: Linux +.. tabs:: - .. code-block:: bash + .. group-tab:: GitHub - xdg-open "Documentation-GENERATED-temp/Result/project/0.0.0/Index.html" + .. code-block:: yaml + :caption: .github/workflows/documentation.yml - .. group-tab:: MacOS + name: test documentation - .. code-block:: bash + on: [ push, pull_request ] - open "Documentation-GENERATED-temp/Result/project/0.0.0/Index.html" + jobs: + tests: + name: documentation + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 - .. group-tab:: Windows + - name: Test if the documentation will render without warnings + run: | + mkdir -p Documentation-GENERATED-temp \ + && docker run --rm --pull always -v $(pwd):/project \ + ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log - .. code-block:: powershell + .. group-tab:: GitLab - start "Documentation-GENERATED-temp/Result/project/0.0.0/Index.html" + .. code-block:: bash + :caption: .gitlab-ci.yml + stages: + - test -.. toctree:: - :hidden: - :glob: + test_documentation: + stage: test + script: + - mkdir -p Documentation-GENERATED-temp + - docker run --rm --pull always -v $(pwd):/project ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --fail-on-log + tags: + - docker - Troubleshooting diff --git a/Documentation/RenderingDocs/Troubleshooting.rst b/Documentation/RenderingDocs/Troubleshooting.rst deleted file mode 100644 index 2ec540c1..00000000 --- a/Documentation/RenderingDocs/Troubleshooting.rst +++ /dev/null @@ -1,189 +0,0 @@ -.. include:: /Includes.rst.txt -.. highlight:: bash -.. index:: Rendering; Troubleshooting -.. _rendering-docs-troubleshooting: - -=========================================== -Troubleshooting local rendering with Docker -=========================================== - -If you run into problems, here are some -helpful hints on how to solve them. - -Remember, you can always ask questions in the **#typo3-documentation** -channel on Slack! `Register for slack `__ -and join the channel, if you have not done so already. - - -.. index:: Rendering; Problems with `source < (docker run ...` -.. _render-troubleshooting-source: - -Problems with `source < (docker run ...` -======================================== - - -.. code-block:: bash - - source <(docker run --rm t3docs/render-documentation show-shell-commands) - dockrun_t3rd makehtml - -If these commands do not work on your platform, try this instead: - -.. code-block:: bash - - mkdir -p ~/bin - docker run --rm t3docs/render-documentation show-shell-commands > ~/bin/t3docs - source ~/bin/t3docs - - -.. _docker-troubleshoot-sample-output-ok: - -Sample output without errors -============================ - -When you run render, you should see some output. If -everything works correctly, the final output should look like this: - -.. code-block:: none - - ... - - We saw these exitcodes (code, count): - { - "0": 86 - } - exiting with exitcode 0 - - ... - -Relevant is the exitcode 0. It indicates that everything executed -smoothly. - - -.. index:: Rendering; Errors -.. _render-troubleshooting-errors: - -Errors that break the rendering -=============================== - -If there are errors which break the rendering, you may see something like: - -.. code-block:: none - - We saw these exitcodes (code, count): - { - "0": 53, - "3": 1, - "22": 7 - } - exiting with exitcode 0 - -Do not let the message *"exiting with exitcode 0"* mislead you. You've -definitely got a problem that needs to be taken care of. - -.. important:: - - If the rendering is not executed correctly, the files in - :file:`Documentation-GENERATED-temp` will still contain - the last rendered results (which are now no longer up to - date) ! - -Scroll back in your terminal to see where the errors occurred: - -.. code-block:: none - - ================================================== - 18-Make-and-build/run_Check-requirements.py - exitcode: 22 - - ================================================== - 20-Postprocess/run_00-Check-requirements.py - exitcode: 22 - - ================================================== - 22-Assemble-results/run_01-Assemble-html-pdf-and-more.py - exitcode: 22 - - ================================================== - 26-Collect-buildinfo/run_Check-requirements.py - exitcode: 22 - -Everything with exitcode != 0 is relevant. Here, we see a problem -with the requirements. This is usually caused by an incorrect path -for including a file. - -Remember, every file includes :file:`Includes.rst.txt` at the top. Check your -latest changes. - -.. code-block:: none - - .. include:: /Includes.rst.txt - -Correct the path, so it will point to the existing Includes.rst.txt (which -should be located in the directory :file:`Documentation`. - - -.. index:: Rendering; Warnings -.. _render-troubleshooting-warnings: - -Warnings -======== - -There may be problems which will not break the rendering but which -should be taken care of. Warnings are listed in the file -:file:`Documentation-GENERATED-temp/Result/project/0.0.0/_buildinfo/warnings.txt` - - -.. index:: Rendering; Incremental -.. _render-troubleshooting-incremental: - -Incremental Rendering -===================== - -After you make changes, you can initiate rendering again. - -This will cause .rst files, that has been changed, to be rendered again. - -If the menu (toctree) has been changed, the menu may not be correctly -displayed for unchanged files because they will not be rendered again. - -If you need a complete rendering, delete the :file:`Documentation-GENERATED-temp` -folder and render again, for example: - -.. code-block:: bash - - rm -rf Documentation-GENERATED-temp - - -Get detailed information -======================== - -If you create a directory :file:`tmp-GENERATED-temp` before you start the rendering, -the toolchain will not remove this directory when it is done. Usually -it cleans up after itself and this directory will be created and then removed. - -The directory contains some additional information for the individual scripts -that have been run. In case of cryptic error messages which you have trouble -interpreting, you may check these files for more information. - -Look for files with ending :file:`err.txt` that are not empty. - -Example output: - -:file:`tmp-GENERATED-temp/RenderDocumentation/2019-05-19_06-37-50_072139/18-Make-and-build/40-Html/xeq-40-Make-html-1-err.txt` - -.. code-block:: bash - - Traceback (most recent call last): - File "/usr/local/lib/python2.7/site-packages/sphinx/cmdline.py", line 303, in main - args.warningiserror, args.tags, args.verbosity, args.jobs) - File "/usr/local/lib/python2.7/site-packages/sphinx/application.py", line 191, in __init__ - self.setup_extension(extension) - File "/usr/local/lib/python2.7/site-packages/sphinx/application.py", line 411, in setup_extension - self.registry.load_extension(self, extname) - File "/usr/local/lib/python2.7/site-packages/sphinx/registry.py", line 318, in load_extension - raise ExtensionError(__('Could not import extension %s') % extname, err) - ExtensionError: Could not import extension sphinxcontrib.googlechart (exception: cannot import name Directive) - - Extension error: - Could not import extension sphinxcontrib.googlechart (exception: cannot import name Directive)