Cleanup documentation and make it more readable

CHANGELOG.rst

@@ -22,7 +22,7 @@ Release 0.11.0 (unreleased)
 * Don't make metadata file part of diff (#267)
 * Fix unneeded project prefix in SVN diffs (#888)
 * Add more tests and documentation for patching (#888)
-* Restrict ``src`` to string only in schema (#889)
+* Restrict ``src`` to string only in schema (#888)
 * Don't consider ignored files for determining local changes (#350)
 
 Release 0.10.0 (released 2025-03-12)

README.md

@@ -27,8 +27,7 @@ problem, but not in a VCS-agnostic way or completely user-friendly way.
 We want self-contained code repositories without any hassle for end-users.
 Dfetch must promote upstreaming changes, but allow for local customizations.
 The problem is described thoroughly in [managing external dependencies](https://embeddedartistry.com/blog/2020/06/22/qa-on-managing-external-dependencies/) and sometimes
-is also known as [*vendoring*](https://stackoverflow.com/questions/26217488/what-is-vendoring).
-See [vendoring](https://dfetch.readthedocs.io/en/latest/vendoring.html) for more information about vendoring.
+is also known as [*vendoring*](https://dfetch.readthedocs.io/en/latest/vendoring.html).
 
 Other tools that do similar things are ``Zephyr's West``, ``CMake ExternalProject`` and other meta tools.
 See [alternatives](https://dfetch.readthedocs.io/en/latest/alternatives.html) for a complete list.

doc/alternatives.rst

@@ -1,12 +1,15 @@
-.. Dfetch documentation master file
+
 
 Alternatives
 ============
 The problem *Dfetch* tries to solve isn't new. There are other tools doing the same.
 In making a proper choice, see the below alternatives.
 
-These alternatives could all be used to use *source* code from another project as part
-of your project.
+There are many alternatives, each with slightly different approaches or focuses: some are designed to manage
+multiple repositories together, some are specialized in :ref:`vendoring` code into your project, and others provide
+build-system or version-control-specific helpers.
+
+Below is a list of notable tools along with their supported version control systems, platforms, and compatibility.
 
 ========================= ===== ===== ========= ======= =================== =======================
  Name                      Git   SVN   Windows   Linux   Language Agnostic   Build System Agnostic
@@ -65,7 +68,7 @@ Dfetch_                     ✔    ✔       ✔        ✔             ✔
 
 .. _`Braid`: https://github.com/cristibalan/braid
 .. _`CGet`: https://github.com/pfultz2/cget
-.. _`CMAke ExternalProject`: https://cmake.org/cmake/help/latest/module/ExternalProject.html
+.. _`CMake ExternalProject`: https://cmake.org/cmake/help/latest/module/ExternalProject.html
 .. _`Combo-layer`: https://wiki.yoctoproject.org/wiki/Combo-layer
 .. _`CPM.cmake`: https://github.com/cpm-cmake/CPM.cmake
 .. _`CPPAN`: https://github.com/cppan/cppan

doc/conf.py

@@ -40,6 +40,7 @@
     "sphinx-jsonschema",
     "sphinxcontrib.programoutput",
     "sphinx_tabs.tabs",
+    "sphinx_autoissues",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -92,6 +93,10 @@
 # Suppress warnings about duplicate labels from argparse directive
 suppress_warnings = ["autosectionlabel.manual"]
 
+# Options for sphinx-autoissues
+issuetracker = "github"
+issuetracker_project = "dfetch-org/dfetch"
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

doc/contributing.rst

@@ -1,4 +1,4 @@
-.. Dfetch documentation master file
+
 
 Contributing
 ============

doc/getting_started.rst

@@ -1,4 +1,4 @@
-.. Dfetch documentation master file
+
 
 Getting Started
 ===============

doc/index.rst

@@ -1,4 +1,4 @@
-.. Dfetch documentation master file
+
 
 .. meta::
    :description: Dfetch is a VCS-agnostic tool that simplifies dependency management by retrieving
@@ -28,14 +28,14 @@
 .. toctree::
    :maxdepth: 2
 
+   installation
    getting_started
    manifest
    manual
    troubleshooting
    contributing
    changelog
    alternatives
-   examples
    vendoring
    legal
    internal
@@ -46,37 +46,19 @@ Dfetch - *a source-only no-hassle project-dependency aggregator*
 What is Dfetch?
 ---------------
 
-We needed a dependency manager that was flexible enough to retrieve dependencies as plain text
+We make products that can last 15+ years; because of this we want to be able to have all sources available
+to build the entire project from source without depending on external resources.
+For this, we needed a dependency manager that was flexible enough to retrieve dependencies as plain text
 from various sources. `svn externals`, `git submodules` and `git subtrees` solve a similar
-problem, but not in a vcs agnostic way or completely user friendly way.
+problem, but not in a VCS-agnostic way or completely user-friendly way.
 We want self-contained code repositories without any hassle for end-users.
 Dfetch must promote upstreaming changes, but allow for local customizations.
+The problem is described thoroughly in `managing external dependencies <https://embeddedartistry.com/blog/2020/06/22/qa-on-managing-external-dependencies/>`_ and sometimes
+is also known as :ref:`vendoring`.
 
-Other tools that do similar things are `Zephyr's West`, `CMake ExternalProject` and other meta tools.
+Other tools that do similar things are ``Zephyr's West``, ``CMake ExternalProject`` and other meta tools.
 See :ref:`alternatives` for a complete list.
 
-Installation
-------------
-`Dfetch` is a python based cross-platform cli tool.
-
-Install the latest release with:
-
-.. code-block::
-
-   pip install dfetch
-
-Or install the latest version from the main branch:
-
-.. code-block::
-
-   pip install https://github.com/dfetch-org/dfetch/archive/main.zip
-
-Once installed dfetch output can be seen.
-
-.. code-block::
-
-   dfetch --version
-
 Basic usage
 -----------
 

doc/installation.rst

@@ -0,0 +1,86 @@
+
+
+
+Installation
+============
+
+From pip
+--------
+
+If you are using python you can install the latest release with:
+
+.. code-block:: bash
+
+   pip install dfetch
+
+Or install the latest version from the main branch:
+
+.. code-block:: bash
+
+   pip install git+https://github.com/dfetch-org/dfetch.git#egg=dfetch
+
+Binary distributions
+--------------------
+
+Each release on the `releases page <https://github.com/dfetch-org/dfetch/releases>`_
+provides pre-built installers for all major platforms, so no compilation is required.
+
+Each installer package has a name in the format ``<version>-<platform>``.
+
+- ``<version>`` shows the software version:
+
+    - If it includes ``dev``, it is a development release (for testing).
+    - If it is only numbers (e.g. ``0.11.0``), it is an official release.
+
+- ``<platform>`` indicates the system the installer is for: ``nix`` (Linux), ``osx`` (Mac), or ``win`` (Windows).
+
+The version is automatically determined from the project and used to name the installer files.
+
+.. tabs::
+
+    .. tab:: Linux
+
+        Download the  ``.deb`` or ``.rpm`` package from the releases page and install it.
+
+        Debian / Ubuntu (``.deb``):
+
+        .. code-block:: bash
+
+            sudo dpkg -i dfetch-<version>-nix.deb
+
+        RPM-based distributions (``.rpm``):
+
+        .. code-block:: bash
+
+            sudo dnf install dfetch-<version>-nix.rpm
+            # or
+            sudo rpm -i dfetch-<version>-nix.rpm
+
+    .. tab:: macOS
+
+        Download the ``.pkg`` package from the releases page and install it.
+
+        .. code-block:: bash
+
+            sudo installer -pkg dfetch-<version>-osx.pkg -target /
+
+    .. tab:: Windows
+
+        Download the ``.msi`` installer and install by double-clicking or use:
+
+        .. code-block:: powershell
+
+            msiexec /i dfetch-<version>-win.msi
+
+        Uninstalling can be done through the regular Add/Remove programs section.
+
+Validating Installation
+-----------------------
+
+Run the following command to verify the installation
+
+.. code-block:: bash
+
+    dfetch environment
+
+.. asciinema:: asciicasts/environment.cast

doc/legal.rst

@@ -1,4 +1,4 @@
-.. Dfetch documentation master file
+
 
 Legal
 =====

doc/manifest.rst

@@ -1,4 +1,4 @@
-.. Dfetch documentation master file
+
 
 Manifest
 ========

doc/manual.rst

@@ -1,4 +1,4 @@
-.. Dfetch documentation master file
+
 
 Manual
 ======

doc/troubleshooting.rst

@@ -1,25 +1,60 @@
-.. Dfetch documentation master file
+
 
 Troubleshooting
 ===============
 
-Although we do our best, *Dfetch* can always do something unexpected.
-A great deal of *Dfetch* functionality is dependent on plain-old command line commands.
+Sometimes *Dfetch* may not behave as expected. This is could be because it relies on
+standard command-line tools such as ``git`` to be available on your system. This section will help you
+diagnose problems and understand what is happening behind the scenes.
+
+Step 1: Check your environment
+------------------------------
+
+Before anything else, it's helpful to see which tools *Dfetch* can detect on your system.
+This shows missing or incompatible dependencies. Run:
+
+.. code-block:: bash
+
+    dfetch environment
+
+Compare the output to the expected tools your commands require.
+
+.. asciinema:: asciicasts/environment.cast
+
+Step 2: Use verbose mode
+------------------------
 
-First of all, it is important to see what tools the system has.
-This can be seen with :ref:`dfetch environment<environment>`.
+If a specific *Dfetch* command gives unexpected results, run it with the ``-v`` flag
+to see exactly what *Dfetch* is doing:
 
-Each command *Dfetch* performs and its result can be shown with increasing the verbosity
-with the `-v` flag. For example, if an :ref:`dfetch import<import>` is giving strange results, re-run it with::
+.. code-block:: bash
 
     dfetch -v import
 
-Reporting issues
-----------------
-We are glad to help, if you you are stuck, either create an issue_ on github or contact us through gitter_!
+Verbose output shows each command *Dfetch* executes and its result, making it easier
+to spot errors, missing tools, or other issues.
+There can be various issues with for instance contacting or authenticating with the remote
+repository or with local settings. By running the ``git`` or ``svn`` command in isolation
+the issue can be shown more clearly.
+
+Step 3: Reporting issues
+------------------------
+
+If you cannot resolve a problem, we're happy to help! Check for any existing `GitHub Issues`_.
+When reporting an issue, please include:
+
+1. The output of ``dfetch environment``
+2. The verbose output of the failing command (``dfetch -v <command>``)
+3. Your operating system and shell information
+
+You can report issues via:
+
+- `GitHub Issues`_
+- `Gitter`_ community chat
+
+.. _`GitHub Issues`: https://github.com/dfetch-org/dfetch/issues
+.. _`Gitter`: https://gitter.im/dfetch-org/community
 
-.. _issue: https://github.com/dfetch-org/dfetch/issues
-.. _gitter: https://gitter.im/dfetch-org/community
 
 Security issues
 ----------------
@@ -29,5 +64,5 @@ You can report issues by opening a confidential issue via `GitHub Security Advis
 `GitHub's private vulnerability reporting`_ for more info. If you have no contact please contact us through
 the mail listed in the pyproject.toml.
 
-.. _`GitHub Security Advisories`: https://github.com/dfetch/dfetch/security/advisories
+.. _`GitHub Security Advisories`: https://github.com/dfetch-org/dfetch/security/advisories
 .. _`GitHub's private vulnerability reporting`: https://docs.github.com/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)

doc/vendoring.rst

@@ -1,7 +1,7 @@
-.. Dfetch documentation master file
 
-Vendoring Dependencies
-======================
+
+Vendoring
+=========
 
 Vendoring is the practice of copying the source code of another project directly
 into your own project's repository. Instead of relying on a package manager to
@@ -322,6 +322,16 @@ Real-world projects using vendoring
 - `Kubernetes - (Go) <https://github.com/kubernetes/kubernetes/tree/master/vendor>`_
 - `Cargo - (Rust) <https://doc.rust-lang.org/cargo/commands/cargo-vendor.html>`_
 
+Real world projects using Dfetch
+--------------------------------
+
+Here are some links to example projects using *Dfetch*.
+
+- `Dfetch`: https://github.com/dfetch-org/dfetch
+- `ModbusScope`: https://github.com/ModbusScope/ModbusScope
+
+Internally we use *Dfetch* for various projects and uses.
+
 
 Further Reading
 ---------------

pyproject.toml

@@ -98,6 +98,7 @@ docs = [
     'sphinx-jsonschema==1.19.2',
     'sphinxcontrib-programoutput==0.18',
     'sphinx-tabs==3.4.7',
+    'sphinx-autoissues==0.0.1',
 ]
 test = ['pytest==8.4.2', 'pytest-cov==7.0.0', 'behave==1.3.3']
 casts = ['asciinema==2.4.0']