Doc improve

.github/workflows/docs.yml

@@ -22,6 +22,8 @@ jobs:
         egress-policy: audit
 
     - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      with:
+        fetch-depth: 0
 
     - name: Install Python
       uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
@@ -79,6 +81,8 @@ jobs:
           egress-policy: audit
 
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
 
       - name: Setup Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0

dfetch/commands/diff.py

@@ -15,9 +15,9 @@
 
 The below statement will generate a patch for ``some-project`` from your manifest.
 
-.. code-block:: sh
+.. code-block:: console
 
-   dfetch diff some-project
+   $ dfetch diff some-project
 
 .. tabs::
 
@@ -41,15 +41,15 @@
 
     .. tab:: Git
 
-        .. code-block:: sh
+        .. code-block:: console
 
-            git apply --check formatted-some-project.patch
+            $ git apply --check formatted-some-project.patch
 
     .. tab:: SVN
 
-        .. code-block:: sh
+        .. code-block:: console
 
-            svn patch formatted-some-project.patch
+            $ svn patch formatted-some-project.patch
 
 """
 

dfetch/commands/format_patch.py

@@ -8,9 +8,9 @@
 root directory. The ``format-patch`` command reformats all patches of a project
 to make them usable for the upstream project.
 
-.. code-block:: sh
+.. code-block:: console
 
-   dfetch format-patch some-project
+   $ dfetch format-patch some-project
 
 .. tabs::
 

dfetch/commands/update_patch.py

@@ -15,9 +15,9 @@
 
 The below statement will update the patch for ``some-project`` from your manifest.
 
-.. code-block:: sh
+.. code-block:: console
 
-   dfetch update-patch some-project
+   $ dfetch update-patch some-project
 
 .. tabs::
 

dfetch/manifest/project.py

@@ -295,9 +295,9 @@
 
     .. tab:: Git
 
-        .. code-block:: sh
+        .. code-block:: console
 
-            git diff --relative=path/to/project HEAD > my_patch.patch
+            $ git diff --relative=path/to/project HEAD > my_patch.patch
 
         For more details see the `git-diff <https://git-scm.com/docs/git-diff>`_ documentation.
 
@@ -307,9 +307,9 @@
 
     .. tab:: SVN
 
-        .. code-block:: sh
+        .. code-block:: console
 
-            svn diff -r HEAD path/to/my_project > my_patch.patch
+            $ svn diff -r HEAD path/to/my_project > my_patch.patch
 
         For more details see the `svn-diff <http://svnbook.red-bean.com/en/1.7/svn.ref.svn.c.diff.html>`_ documentation.
 

doc/conf.py

@@ -12,8 +12,12 @@
 #
 import os
 import sys
+from importlib.metadata import PackageNotFoundError, version
 
-from dfetch import __version__
+try:
+    __version__ = version("dfetch")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
 
 # Prevent ANSI color codes in command output captured by sphinxcontrib.programoutput.
 # Python 3.13+ argparse emits colors when FORCE_COLOR is set; NO_COLOR suppresses
@@ -250,7 +254,13 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, f"dfetch-{__version__}.tex", "Dfetch Documentation", "Dfetch", "manual"),
+    (
+        master_doc,
+        f"dfetch-{__version__}.tex",
+        "Dfetch Documentation",
+        "Dfetch",
+        "manual",
+    ),
 ]
 
 

doc/howto/adding-a-project.rst

@@ -57,17 +57,17 @@ Pass the repository URL to ``dfetch add`` and it will append a new entry to
 (branches and tags), selects the default branch, and guesses a destination
 path based on your existing projects.
 
-.. code-block:: sh
+.. code-block:: console
 
-    dfetch add https://github.com/some-org/some-repo.git
+  $ dfetch add https://github.com/some-org/some-repo.git
 
 .. asciinema:: ../asciicasts/add.cast
 
 Override individual fields with flags:
 
-.. code-block:: sh
+.. code-block:: console
 
-    dfetch add \
+  $ dfetch add \
       --name mylib \
       --dst ext/mylib \
       --version v2.0 \
@@ -86,9 +86,9 @@ The ``--interactive`` (``-i``) flag starts a step-by-step wizard.  Use it
 when you want to browse available branches and tags, choose a sub-directory
 inside the remote repository, or configure which paths to ignore.
 
-.. code-block:: sh
+.. code-block:: console
 
-    dfetch add -i https://github.com/some-org/some-repo.git
+  $ dfetch add -i https://github.com/some-org/some-repo.git
 
 .. asciinema:: ../asciicasts/interactive-add.cast
 
@@ -106,9 +106,9 @@ The wizard walks through each field in turn:
 
 You can pre-fill any field to skip its prompt:
 
-.. code-block:: sh
+.. code-block:: console
 
-    dfetch add -i --version main \
+  $ dfetch add -i --version main \
                   --src lib/core \
                   https://github.com/some-org/some-repo.git
 

doc/howto/check-ci.rst

@@ -25,9 +25,9 @@ Running dfetch check in CI
 Without extra flags the results are printed to stdout and the build fails if
 any issue is found:
 
-.. code-block:: sh
+.. code-block:: console
 
-    dfetch check
+    $ dfetch check
 
 Pass a ``--*-json`` flag to write a machine-readable report *and* continue
 collecting results before deciding the build outcome (each section below shows

doc/howto/migration.rst

@@ -20,60 +20,61 @@ Choose the guide that matches your current setup:
 From Git submodules
 -------------------
 
-**Before you start**, make sure:
+.. note::
 
-- Your repository is fully up-to-date (``git pull``).
-- All submodules are initialised and checked out:
+    Before you start, make sure your repository is fully up-to-date and
+    all submodules are initialised and checked out:
 
-  .. code-block:: console
+    .. code-block:: console
 
-      $ git submodule update --init --recursive
+        $ git pull
+        $ git submodule update --init --recursive
 
 **Steps**
 
 1. Generate a manifest from the existing submodules:
 
-   .. code-block:: console
+    .. code-block:: console
 
-       $ dfetch import
+        $ dfetch import
 
-   This writes a ``dfetch.yaml`` file in the current directory listing each
-   submodule as a *Dfetch* project entry, pinned to the commit that is
-   currently checked out.
+    This writes a ``dfetch.yaml`` file in the current directory listing each
+    submodule as a *Dfetch* project entry, pinned to the commit that is
+    currently checked out.
 
 2. Remove all Git submodules.  For each submodule (replace ``<path>`` with
    the submodule path, e.g. ``ext/mylib``):
 
-   .. code-block:: console
+    .. code-block:: console
 
-       $ git submodule deinit -f <path>
-       $ git rm -f <path>
-       $ rm -rf .git/modules/<path>
+        $ git submodule deinit -f <path>
+        $ git rm -f <path>
+        $ rm -rf .git/modules/<path>
 
-   Repeat until ``git submodule status`` returns nothing.  Commit the
-   result:
+    Repeat until ``git submodule status`` returns nothing.  Commit the
+    result:
 
-   .. code-block:: console
+    .. code-block:: console
 
-       $ git commit -m "chore: remove git submodules (switching to Dfetch)"
+        $ git commit -m "chore: remove git submodules (switching to Dfetch)"
 
-   .. seealso::
+    .. seealso::
 
       `How do I remove a submodule?
       <https://stackoverflow.com/questions/1260748/>`_
 
 3. Fetch all projects into your repository:
 
-   .. code-block:: console
+    .. code-block:: console
 
-       $ dfetch update
+        $ dfetch update
 
 4. Commit the fetched files:
 
-   .. code-block:: console
+    .. code-block:: console
 
-       $ git add .
-       $ git commit -m "chore: vendor dependencies with Dfetch"
+        $ git add .
+        $ git commit -m "chore: vendor dependencies with Dfetch"
 
 .. scenario-include:: ../features/import-from-git.feature
 

doc/howto/patching.rst

@@ -27,9 +27,9 @@ After fetching a project with :ref:`dfetch update <update>`, make your edits
 directly in the vendored source tree.  Once you are happy with the changes,
 run:
 
-.. code-block:: sh
+.. code-block:: console
 
-    dfetch diff some-project
+    $ dfetch diff some-project
 
 *Dfetch* compares the working tree against the revision recorded in the
 metadata file and writes a patch file named ``some-project.patch`` (or
@@ -86,9 +86,9 @@ As your local edits evolve — or when the upstream version changes — the
 existing patch file may no longer apply cleanly.  Instead of manually
 regenerating it, run:
 
-.. code-block:: sh
+.. code-block:: console
 
-    dfetch update-patch some-project
+    $ dfetch update-patch some-project
 
 This regenerates the last patch for ``some-project`` from the current working
 tree, keeping the upstream revision unchanged.  It is safe to run repeatedly
@@ -116,9 +116,9 @@ directory inside your repository.  Most upstream projects expect patches to be
 relative to their own root, which is a different path.  To reformat all patches
 for a project:
 
-.. code-block:: sh
+.. code-block:: console
 
-    dfetch format-patch some-project
+    $ dfetch format-patch some-project
 
 This writes a ``formatted-some-project.patch`` file (or one file per patch if
 there are several) that is ready to attach to a pull request or send by email.
@@ -130,15 +130,15 @@ You can verify the formatted patch applies cleanly before submitting:
 
     .. tab:: Git
 
-        .. code-block:: sh
+        .. code-block:: console
 
-            git apply --check formatted-some-project.patch
+            $ git apply --check formatted-some-project.patch
 
     .. tab:: SVN
 
-        .. code-block:: sh
+        .. code-block:: console
 
-            svn patch formatted-some-project.patch
+            $ svn patch formatted-some-project.patch
 
 .. asciinema:: ../asciicasts/format-patch.cast
 

doc/howto/sbom.rst

@@ -11,13 +11,14 @@ license policy across an organisation.
 
 .. asciinema:: ../asciicasts/sbom.cast
 
-.. code-block:: sh
+.. code-block:: console
 
-    dfetch report -t sbom -o dfetch.cdx.json
+    $ dfetch report -t sbom -o dfetch.cdx.json
 
-*Dfetch* parses each project's license at fetch time and stores it in the
-``.dfetch_data.yaml`` metadata file, so reports stay accurate without
-re-fetching.
+*Dfetch* parses each project's license at report time, it can recognise common
+license files and detect the license type with high accuracy. If a project doesn't
+include a license file or has an unknown license, *Dfetch* keeps the license field
+empty in the SBOM.
 
 Archive dependencies (``tar.gz``, ``zip``, …) are recorded with a
 ``distribution`` external reference.  When an ``integrity.hash:`` field is set

doc/howto/troubleshooting.rst

@@ -15,7 +15,7 @@ This shows missing or incompatible dependencies. Run:
 
 .. code-block:: bash
 
-    dfetch environment
+    $ dfetch environment
 
 Compare the output to the expected tools your commands require.
 
@@ -29,7 +29,7 @@ to see exactly what *Dfetch* is doing:
 
 .. code-block:: bash
 
-    dfetch -v import
+    $ dfetch -v import
 
 Verbose output shows each command *Dfetch* executes and its result, making it easier
 to spot errors, missing tools, or other issues.