docs: Refine links and command examples (#62)

sushant-suse · web-flow · commit 01cbfe570a0f · 2025-07-22T17:10:33.000+05:30
* updated link of RNC, modified content of TOML and UV Signed-off-by: sushant-suse <sushant.gaurav@suse.com> * added importance of --frozen flag Signed-off-by: sushant-suse <sushant.gaurav@suse.com> * added documentation link of reStructuredText, Sphinx, and uv in Overview Signed-off-by: sushant-suse <sushant.gaurav@suse.com> * added documentation link of towncrier Signed-off-by: sushant-suse <sushant.gaurav@suse.com> * added openSUSE, gh, and jing links; modified the content of external tools Signed-off-by: sushant-suse <sushant.gaurav@suse.com> * modified style of link to VS code download page Signed-off-by: sushant-suse <sushant.gaurav@suse.com> * updated commands and removed $ sign Signed-off-by: sushant-suse <sushant.gaurav@suse.com> * docs: Add news fragment for documentation improvements (PR #62) * updated back-ticks issue Signed-off-by: sushant-suse <sushant.gaurav@suse.com> --------- Signed-off-by: sushant-suse <sushant.gaurav@suse.com>
diff --git a/changelog.d/62.doc.rst b/changelog.d/62.doc.rst
@@ -0,0 +1,6 @@
+Improved documentation clarity and usability:
+
+* Updated external links for ``uv``, ``towncrier``, ``reStructuredText``, Sphinx, ``jing``, and RNC schema to official resources.
+* Removed ``$`` prefixes from shell command examples for easier copy-pasting.
+* Added a brief explanation for the ``--frozen`` flag usage with :command:`uv sync`.
+* Enhanced descriptions and added links in the "External tools" section.
diff --git a/devel/README.rst b/devel/README.rst
@@ -24,7 +24,7 @@ The directory :file:`devel/` contains some helper tools to make development easi
     .. code-block:: shell-session
        :caption: Activating development aliases
 
-       $ source devel/activate-aliases.sh
+       source devel/activate-aliases.sh
 
 * :command:`bump-version.sh`
    Bumps the version of the project. To bump the minor version, use
diff --git a/docs/source/developer/build-changelog.rst b/docs/source/developer/build-changelog.rst
@@ -16,7 +16,7 @@ To build the changelog, make sure you have:
    .. code-block:: shell-session
       :caption: Build a combined changelog from news fragments
 
-      $ towncrier build [--yes]
+      towncrier build [--yes]
 
    After this command, the :file:`CHANGELOG.rst` file in the root directory is updated and all news fragments are removed from the directory :file:`changelog.d/`.
 
diff --git a/docs/source/developer/build-docs.rst b/docs/source/developer/build-docs.rst
@@ -13,6 +13,6 @@ To build the documentation for this project, use the following steps:
       :caption: Building the documentation
       :name: makedocs
 
-      $ makedocs
+      makedocs
 
 #. Find the generated documentation in the :file:`docs/build/html` directory.
diff --git a/docs/source/developer/bump-version.rst b/docs/source/developer/bump-version.rst
@@ -10,7 +10,7 @@ This project follows :term:`Semantic Versioning <SemVer>`. To bump the version,
    :caption: Bumping the minor part
    :name: sh-bump-version
 
-   $ ./devel/bump-version.sh minor
+   ./devel/bump-version.sh minor
 
 This script automates the versioning process with the following actions:
 
diff --git a/docs/source/developer/design.rst b/docs/source/developer/design.rst
@@ -112,7 +112,7 @@ The project follows a modular design structure, with the following main componen
 
 * **Documentation directory**: The documentation is stored in the :file:`docs` directory, which contains the Sphinx documentation source files.
 
-* **Changelog**: The project maintains a :file:`CHANGELOG.rst` file, which documents the changes made in each version of the project. The changelog is automatically generated using the towncrier tool. It uses the :file:`changelog.d` directory to store individual change files.
+* **Changelog**: The project maintains a :file:`CHANGELOG.rst` file, which documents the changes made in each version of the project. The changelog is automatically generated using the `towncrier <https://towncrier.readthedocs.io/en/stable/>`_ tool. It uses the :file:`changelog.d` directory to store individual change files.
 
 
 
diff --git a/docs/source/developer/install-vscode.rst b/docs/source/developer/install-vscode.rst
@@ -10,7 +10,7 @@ Follow these steps to set up VSCode for working with this project:
 
 #. Install Visual Studio Code
 
-   Download and install VSCode from the official website: https://code.visualstudio.com/
+   Download and install VSCode from the `official website <https://code.visualstudio.com/>`_.
 
 #. Install the recommended extensions
 
diff --git a/docs/source/developer/overview.rst b/docs/source/developer/overview.rst
@@ -13,7 +13,7 @@ The project's repository is structured in a way that allows for easy navigation
 
 * **pyproject.toml**
 
-  The :file:`pyproject.toml` file is used to define the project's metadata, dependencies, and build system requirements. It is a standardized way to configure Python projects and is used by tools such as :command:`uv`.
+  The :file:`pyproject.toml` file is used to define the project's metadata, dependencies, and build system requirements. It is a standardized way to configure Python projects and is used by tools such as :command:`uv` (see `uv docs <https://docs.astral.sh/uv/>`_).
   The :command:`uv` create a lock file :file:`uv.lock` based on the dependencies defined in :file:`pyproject.toml`. This lock file ensures that the same versions of dependencies are used across different environments, providing consistency and reliability.
 
 * **uv**
@@ -23,4 +23,4 @@ The project's repository is structured in a way that allows for easy navigation
 
 * **Documentation**
 
-  The documentation is built using reStructuredText and Sphinx. The source files for the documentation are located in the :file:`docs/` directory. The documentation targets users and developers, providing information on how to use the project, its features, and how to change it.
+  The documentation is built using `reStructuredText <https://docutils.sourceforge.io/rst.html>`_ and `Sphinx <https://www.sphinx-doc.org/en/master/>`_. The source files for the documentation are located in the :file:`docs/` directory. The documentation targets users and developers, providing information on how to use the project, its features, and how to change it.
diff --git a/docs/source/developer/prepare-environment.rst b/docs/source/developer/prepare-environment.rst
@@ -72,7 +72,7 @@ The following steps are recommended to set up your development environment:
       :caption: Creating a virtual environment with |uv|
       :name: uv-venv
 
-      $ uv venv --prompt venv313 --python 3.13 .venv
+      uv venv --prompt venv313 --python 3.13 .venv
 
    Keep in mind that the Python version used in the virtual environment should match the version specified in the :file:`pyproject.toml` file.
    
@@ -85,7 +85,7 @@ The following steps are recommended to set up your development environment:
       :caption: Synchronizing the virtual environment with the development dependencies
       :name: uv-sync-devel
 
-      $ uv sync --frozen --group devel
+      uv sync --frozen --group devel
 
    The option ``--frozen`` ensures that the dependencies are installed exactly as specified in the lock file, preventing any unexpected changes.
 
@@ -95,7 +95,7 @@ The following steps are recommended to set up your development environment:
       :caption: Activating the shell aliases for development
       :name: activate-aliases
 
-      $ source devel/activate-aliases.sh
+      source devel/activate-aliases.sh
 
 
 After completing these steps, your development environment is ready to go.
@@ -113,7 +113,7 @@ To get started, clone this repository to your local machine (you need VPN access
 
 .. code-block:: shell-session
 
-   $ git clone https://gitlab.suse.de/susedoc/docserv-config.git
+   git clone https://gitlab.suse.de/susedoc/docserv-config.git
 
 You will later need to point ``docbuild`` to the location of this cloned
 repository in your configuration.
diff --git a/docs/source/developer/project-dependencies.rst b/docs/source/developer/project-dependencies.rst
@@ -27,7 +27,7 @@ All of the above points (except for the last one) are defined in the :file:`pypr
 Operating System
 ----------------
 
-The code is developed on openSUSE, but should work on any Linux distribution.
+The code is developed on `openSUSE <https://www.opensuse.org/>`_, but should work on any Linux distribution.
 The project will support MacOS too. It's currently not planned to support Windows.
 
 
@@ -41,7 +41,7 @@ The project will support MacOS too. It's currently not planned to support Window
 Python
 ------
 
-The minimal Python version is defined in the :file:`pyproject.toml` file. It's strongly recommended to have the Python versions managed by |uv|.
+The minimal Python version is defined in the :file:`pyproject.toml` file. It is strongly recommended to have the Python versions managed by |uv|.
 
 
 Editor
@@ -53,8 +53,8 @@ You can use any editor you like. Rudimentary support is available for `VSCode <h
 External tools
 --------------
 
-* |daps|: our tool to build documentation. This is an obligatory requirement. This adds other dependencies.
-* |uv|, the Python package manager. This is explained in :ref:`devel-helpers`.
-* :command:`make` is used to build the documentation.
-* :command:`jing`: for validation the XML configuration files.
-* :command:`gh`: optional tool for interacting with GitHub, see :ref:`github-cli`.
+* |daps|: Our tool to build documentation. This is an obligatory requirement. This adds other dependencies.
+* |uv|: The Python package and project manager. This is explained in :ref:`devel-helpers`.
+* :command:`make`: Used to orchestrate the documentation build process.
+* `jing <https://jing.nu/>`: For validating the XML configuration files against their RNC schema.
+* `gh <https://cli.github.com/>`: The GitHub CLI, an optional tool for GitHub interactions. See :ref:`github-cli`.
diff --git a/docs/source/developer/run-ipython.rst b/docs/source/developer/run-ipython.rst
@@ -15,7 +15,7 @@ This is useful for experimenting with the project's code and for debugging.
    :caption: Running IPython using |uv| with alias :ref:`uipython <devel-helpers>`
    :name: sh-running-ipython
 
-   $ uipython
+   uipython
 
 
 After the IPython shell is loaded, you can use the normal import without changing the import path:
diff --git a/docs/source/developer/run-testsuite.rst b/docs/source/developer/run-testsuite.rst
@@ -9,15 +9,15 @@ To run the full test suite, use the following command:
    :caption: Running pytest directly with |uv|
    :name: running-pytest-with-uv
 
-   $ uv run --frozen pytest
+   uv run --frozen pytest
 
 or use the alias (see :ref:`devel-helpers` for more information):
 
 .. code-block:: shell-session
    :caption: Running pytest using |uv| with alias :ref:`upytest <devel-helpers>`
    :name: running-upytest
 
-   $ upytest
+   upytest
 
 This command will execute all the tests defined in the project. The test suite is designed to ensure that all components of the project are functioning correctly and to catch any regressions.
 
@@ -27,8 +27,8 @@ In case you want to run a specific test or a subset of tests, specify the path t
    :caption: Running specific tests
    :name: running-specific-tests
 
-   $ upytest tests/test_module.py
-   $ upytest tests/test_module.py::test_function_name
+   upytest tests/test_module.py
+   upytest tests/test_module.py::test_function_name
 
 In the first example, all tests in `test_module.py` will be executed, while in the second example, only the specific test function `test_function_name` will be run.
 
@@ -38,4 +38,4 @@ If one of the test fails and you want to repeat the test run after you have fixe
    :caption: Running only the last failed tests
    :name: running-last-failed-tests
 
-   $ upytest --lf
+   upytest --lf
diff --git a/docs/source/developer/update-package.rst b/docs/source/developer/update-package.rst
@@ -6,5 +6,5 @@ time keep the development group dependencies intact, use the following command:
 
 .. code-block:: shell-session
 
-   $ uv sync --group devel --upgrade-package pydantic-core
+   uv sync --group devel --upgrade-package pydantic-core
 
diff --git a/docs/source/developer/update-project.rst b/docs/source/developer/update-project.rst
@@ -13,5 +13,5 @@ In some cases, it may be helpful to manually update the project.
    :caption: Updating the project
    :name: uv-pip-update-project
 
-   $ uv pip install --upgrade -e .
+   uv pip install --upgrade -e .
 
diff --git a/docs/source/user/clone.rst b/docs/source/user/clone.rst
@@ -8,7 +8,7 @@ During the process of building documentation, the script clones Git repositores
 .. code-block:: shell
    :caption: Synopsis of :command:`docbuild repo clone`
 
-   $ docbuild repo clone [OPTIONS] REPO [REPO ...]
+   docbuild repo clone [OPTIONS] REPO [REPO ...]
 
 The ``REPO`` argument can be specified in various formats, such as:
 
@@ -34,10 +34,10 @@ For example, to clone the ``https://github.com/SUSE/doc-modular.git`` repository
    :caption: Example of cloning a repository
    :name: docbuild-repo-clone
 
-   $ docbuild repo clone https://github.com/SUSE/doc-modular.git
-   $ docbuild repo clone gh://SUSE/doc-modular
-   $ docbuild repo clone gh://suse/doc-modular
-   $ docbuild repo clone SUSE/doc-modular
+   docbuild repo clone https://github.com/SUSE/doc-modular.git
+   docbuild repo clone gh://SUSE/doc-modular
+   docbuild repo clone gh://suse/doc-modular
+   docbuild repo clone SUSE/doc-modular
 
 The command will clone the repository into the permanent storage directory.
 You can find the exact path by running:
@@ -46,7 +46,7 @@ You can find the exact path by running:
    :caption: Find the permanent storage directory
    :name: docbuild-repo-dir
 
-   $ docbuild repo dir
+   docbuild repo dir
    /var/cache/docbuild/repos/permanent-full/
 
 To get a list of all available repositories in the permanent storage, use:
@@ -55,4 +55,4 @@ To get a list of all available repositories in the permanent storage, use:
    :caption: List all repositories in permanent storage
    :name: docbuild-repo-list
 
-   $ docbuild repo list
+   docbuild repo list
diff --git a/docs/source/user/config.rst b/docs/source/user/config.rst
@@ -29,6 +29,6 @@ To deal with different environments without having to type the full command each
    :caption: Example aliases for different configuration files
    :name: docbuild-aliases
 
-   $ alias docbuild-prod='docbuild --env-config env.production.toml'
-   $ alias docbuild-test='docbuild --env-config env.testing.toml'
-   $ alias docbuild-dev='docbuild --env-config env.devel.toml'
+   alias docbuild-prod='docbuild --env-config env.production.toml'
+   alias docbuild-test='docbuild --env-config env.testing.toml'
+   alias docbuild-dev='docbuild --env-config env.devel.toml'
diff --git a/docs/source/user/config/application.rst b/docs/source/user/config/application.rst
@@ -17,7 +17,7 @@ If you want to override the default search strategy, use the ``--app-config`` op
 .. code-block:: shell-session
    :caption: Showing configuration files
 
-   $ docbuild config app
+   docbuild config app
    # Application config files '/home/tux/repos/GH/opensuse/docbuild/.config.toml'
    [ ... content ...]
 
diff --git a/docs/source/user/config/environment.rst b/docs/source/user/config/environment.rst
@@ -10,7 +10,7 @@ If you want to override the default, use the ``--env-config`` option to specify
 .. code-block:: shell-session
    :caption: Showing env configuration content
 
-   $ docbuild --env-config env.develop.toml config env
+   docbuild --env-config env.develop.toml config env
    # ENV Config file '/home/tux/repos/GH/opensuse/docbuild/env.production.toml'
    [ ... content ...]
 
diff --git a/docs/source/user/config/index.rst b/docs/source/user/config/index.rst
@@ -17,7 +17,7 @@ Keep in mind that these defaults may not be suitable for all use cases, and it i
 
 .. admonition:: TOML as default format
 
-   Both configuration types are written in TOML format, which is a human-readable data serialization standard. See https://toml.io/en/ for more information on TOML syntax and structure.
+   Both configuration types are written in TOML format, which is a human-readable data serialization standard. See `TOML docs <https://toml.io/en/>_` for more information on its syntax and structure.
 
 The following subsections provide more details on how to view and manage the configuration files for both application and environment settings.
 
diff --git a/docs/source/user/install.rst b/docs/source/user/install.rst
@@ -20,7 +20,7 @@ Preparing for Installation
 It is highly recommended to use the `package and project manager uv <https://docs.astral.sh/uv>`_ to install the docbuild tool. This ensures that all dependencies are managed correctly and that the installation is reproducible across different environments.
 
 There are different methods to install the :command:`uv` package manager
-(see `Installing uv <https://docs.astral.sh/uv/getting-started/installation/>`_.). In this case, use the standalone installer:
+(see `Installing uv <https://docs.astral.sh/uv/getting-started/installation/>`_). In this case, use the standalone installer:
 
 
 1. **Install uv**
@@ -29,7 +29,7 @@ There are different methods to install the :command:`uv` package manager
 
    .. code-block:: shell-session
 
-      $ curl -sSfL https://astral.sh/uv/install.sh | sh
+      curl -sSfL https://astral.sh/uv/install.sh | sh
 
 
    This will install two commands :command:`uv` and :command:`uvx` in :file:`~/.local/bin/`. Make sure this directory is in your :envvar:`PATH` environment variable.
@@ -40,9 +40,9 @@ There are different methods to install the :command:`uv` package manager
 
    .. code-block:: shell-session
 
-      $ type uv
+      type uv
       uv is hashed (/home/tux/.local/bin/uv)
-      $ uv --version
+      uv --version
       ...
 
    You should see the version of :command:`uv` printed in the terminal.
@@ -53,7 +53,7 @@ There are different methods to install the :command:`uv` package manager
 
    .. code-block:: shell-session
 
-      $ uv python install 3.13
+      uv python install 3.13
 
    The previous command downloads Python 3.13 and install it in the directory :file:`~/.local/share/uv/python/<VERSION>`.
 
@@ -63,7 +63,7 @@ There are different methods to install the :command:`uv` package manager
 
    .. code-block:: shell-session
 
-      $ uv python list
+      uv python list
       cpython-3.14.0b1-linux-x86_64-gnu                 <download available>
       cpython-3.14.0b1+freethreaded-linux-x86_64-gnu    <download available>
       cpython-3.13.4-linux-x86_64-gnu                   /home/tux/.local/share/uv/python/cpython-3.13.4-linux-x86_64-gnu/bin/python3.13
@@ -83,8 +83,8 @@ Installing the tool
 
    .. code-block:: shell-session
 
-      $ git clone https://github.com/openSUSE/docbuild.git
-      $ cd docbuild
+      git clone https://github.com/openSUSE/docbuild.git
+      cd docbuild
 
 2. **Create a virtual environment**
 
@@ -93,7 +93,7 @@ Installing the tool
 
    .. code-block:: shell-session
 
-      $ uv venv --prompt "venv313" .venv
+      uv venv --prompt "venv313" .venv
 
    This will create a virtual environment in the directory `.venv`.
 
@@ -103,11 +103,12 @@ Installing the tool
 
    .. code-block:: shell-session
 
-      $ uv sync --frozen
+      uv sync --frozen
       Resolved 29 packages in 586ms
       Built docbuild @ file:///.../docbuild
       Installed 15 packages in 2.11s
 
+   The `--frozen` flag is used here to ensure that `uv` installs dependencies exactly as specified in the `uv.lock` file. This is crucial for **reproducible builds** and maintaining a **consistent environment** across different machines or deployments, as it prevents `uv` from attempting to resolve and potentially update dependency versions.
 
 .. _get-xml-config:
 
@@ -119,4 +120,4 @@ Formerly known as the *Docserv XML configs*. These configuration files defines t
 The tool needs the XML configuration to build the documentation correctly. The XML configuration is not part of the docbuild tool itself, but it is required to run the tool.
 
 Clone the |gl_xmlconfig| to your machine where you can access it easily.
-As an alternative, use the RNC schema from :gh_tree:`src/docbuild/config/xml/data/` to create your own configuration.
+As an alternative, use the `RNC schema <https://www.oasis-open.org/committees/relax-ng/compact-20021121.html>_` from :gh_tree:`src/docbuild/config/xml/data/` to create your own configuration.
diff --git a/docs/source/user/run-docbuild.rst b/docs/source/user/run-docbuild.rst
@@ -6,10 +6,10 @@ If you have installed the docbuild tool from the source code, run it using
 
 .. code-block:: shell-session
 
-   $ uv run docbuild --help
+   uv run docbuild --help
 
 In case you have installed different Python versions using :command:`uv python install` (see :ref:`prepare-installation`), specify the Python version to use with the ``-P``/``--python <VERSION>`` option:
 
 .. code-block:: shell-session
 
-   $ uv run --python 3.14 docbuild --help
+   uv run --python 3.14 docbuild --help

Original file line number	Diff line number	Diff line change
`@@ -112,7 +112,7 @@ The project follows a modular design structure, with the following main componen`
`112`	`112`
`113`	`113`	* Documentation directory: The documentation is stored in the :file:`docs` directory, which contains the Sphinx documentation source files.
`114`	`114`
`115`		-* Changelog: The project maintains a :file:`CHANGELOG.rst` file, which documents the changes made in each version of the project. The changelog is automatically generated using the towncrier tool. It uses the :file:`changelog.d` directory to store individual change files.
	`115`	+* Changelog: The project maintains a :file:`CHANGELOG.rst` file, which documents the changes made in each version of the project. The changelog is automatically generated using the `towncrier <https://towncrier.readthedocs.io/en/stable/>`_ tool. It uses the :file:`changelog.d` directory to store individual change files.
`116`	`116`
`117`	`117`
`118`	`118`