diff options
Diffstat (limited to 'doc/tutorial')
| -rw-r--r-- | doc/tutorial/automatic-doc-generation.rst | 2 | ||||
| -rw-r--r-- | doc/tutorial/deploying.rst | 15 | ||||
| -rw-r--r-- | doc/tutorial/describing-code.rst | 12 | ||||
| -rw-r--r-- | doc/tutorial/getting-started.rst | 2 |
4 files changed, 13 insertions, 18 deletions
diff --git a/doc/tutorial/automatic-doc-generation.rst b/doc/tutorial/automatic-doc-generation.rst index b47673d..8d9c9c9 100644 --- a/doc/tutorial/automatic-doc-generation.rst +++ b/doc/tutorial/automatic-doc-generation.rst @@ -160,6 +160,6 @@ originally used the corresponding ``autodoc`` directive, in this case in the .. note:: The generated files are based on `Jinja2 - templates <https://jinja2docs.readthedocs.io/>`_ that + templates <https://jinja.palletsprojects.com/>`_ that :ref:`can be customized <autosummary-customizing-templates>`, but that is out of scope for this tutorial. diff --git a/doc/tutorial/deploying.rst b/doc/tutorial/deploying.rst index e16abdf..6b7913f 100644 --- a/doc/tutorial/deploying.rst +++ b/doc/tutorial/deploying.rst @@ -109,16 +109,11 @@ The quickest way to upload an existing project to GitHub is to: sources, complicating your workflow. These steps do not require access to the command line or installing any -additional software. To learn more, you can: +additional software. To learn more, read `this quickstart tutorial`_ or +consult the `official GitHub documentation`_ -- Follow `this interactive GitHub course`_ to learn more about how the GitHub - interface works. -- Read `this quickstart tutorial`_ to install extra software on your machine - and have more flexibility. You can either use the Git command line, or the - GitHub Desktop application. - -.. _this interactive GitHub course: https://lab.github.com/githubtraining/introduction-to-github .. _this quickstart tutorial: https://docs.github.com/en/get-started/quickstart +.. _official GitHub documentation: https://docs.github.com/en/get-started GitLab ~~~~~~ @@ -192,11 +187,11 @@ contents: permissions: contents: write steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Build HTML uses: ammaraskar/sphinx-action@master - name: Upload artifacts - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: html-docs path: docs/build/html/ diff --git a/doc/tutorial/describing-code.rst b/doc/tutorial/describing-code.rst index 24fea38..16feb2a 100644 --- a/doc/tutorial/describing-code.rst +++ b/doc/tutorial/describing-code.rst @@ -8,7 +8,7 @@ will describe code objects instead. Sphinx supports documenting code objects in several languages, namely Python, C, C++, JavaScript, and reStructuredText. Each of them can be documented using a series of directives and roles grouped by -:doc:`domain </usage/restructuredtext/domains>`. For the remainder of the +:doc:`domain </usage/domains/index>`. For the remainder of the tutorial you will use the Python domain, but all the concepts seen in this section apply for the other domains as well. @@ -21,9 +21,9 @@ Documenting Python objects ~~~~~~~~~~~~~~~~~~~~~~~~~~ Sphinx offers several roles and directives to document Python objects, -all grouped together in :ref:`the Python domain <python-domain>`. For example, -you can use the :rst:dir:`py:function` directive to document a Python function, -as follows: +all grouped together in :doc:`the Python domain </usage/domains/python>`. +For example, you can use the :rst:dir:`py:function` directive to document +a Python function, as follows: .. code-block:: rst :caption: docs/source/usage.rst @@ -228,7 +228,7 @@ for easy examination. It is now time to fix the function: def get_random_ingredients(kind=None): return ["shells", "gorgonzola", "parsley"] -And finally, ``make test`` reports success! +And finally, ``make doctest`` reports success! For big projects though, this manual approach can become a bit tedious. In the next section, you will see :doc:`how to automate the @@ -246,7 +246,7 @@ C, C++, JavaScript, and reStructuredText. Third-party extensions may define domains for more languages, such as - `Fortran <https://sphinx-fortran.readthedocs.io>`_, -- `Julia <http://bastikr.github.io/sphinx-julia>`_, or +- `Julia <https://bastikr.github.io/sphinx-julia>`_, or - `PHP <https://github.com/markstory/sphinxcontrib-phpdomain>`_. For example, to document a C++ type definition, you would use the built-in diff --git a/doc/tutorial/getting-started.rst b/doc/tutorial/getting-started.rst index 5cf0b38..678f08d 100644 --- a/doc/tutorial/getting-started.rst +++ b/doc/tutorial/getting-started.rst @@ -104,7 +104,7 @@ the documentation as HTML for the first time. To do that, run this command: .. code-block:: console - (.venv) $ sphinx-build -b html docs/source/ docs/build/html + (.venv) $ sphinx-build -M html docs/source/ docs/build/ And finally, open ``docs/build/html/index.html`` in your browser. You should see something like this: |