Fix #891 - Update docs

CHANGELOG.rst

@@ -18,6 +18,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)
 
 Release 0.10.0 (released 2025-03-12)
 ====================================

README.md

@@ -19,13 +19,16 @@
 
 **DFetch can manage dependencies**
 
-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 not being dependent on the existence of the remote resource.
+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 [here](https://embeddedartistry.com/blog/2020/06/22/qa-on-managing-external-dependencies/) and sometimes
+The problem is described thoroughly [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.
 
 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.

dfetch/manifest/project.py

@@ -20,7 +20,7 @@
 
 Revision/Branch/Tag
 ###################
-When no version is provided the latest version of the default branch (e.g. `trunk`, `master`) of
+When no version is provided the latest version of the default branch (e.g. `trunk`, `master`, `main`) of
 a project will be chosen. Since we want more control on what project is retrieved the
 ``revision:``, ``branch:`` and ``tag:`` attributes can help.
 Below manifest will download tag ``v1.13`` of ``mymodule``.

dfetch/reporting/sbom_reporter.py

@@ -12,7 +12,7 @@
 
 .. scenario-include:: ../features/report-sbom.feature
    :scenario:
-        An fetched project generates an sbom
+        A fetched project generates a json sbom
 
 Gitlab
 ------

dfetch/resources/schema.yaml

@@ -31,8 +31,7 @@ mapping:
                    "remote": { type: str }
                    "patch": { type: str }
                    "vcs": { type: str, enum: ['git', 'svn'] }
-                   "src":
-                      type: any
+                   "src": { type: str }
                    "ignore":
                         required: False
                         type: seq

doc/conf.py

@@ -12,6 +12,7 @@
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
+# pylint: disable=invalid-name
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -34,7 +35,6 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-# extensions = ['sphinx.ext.autodoc', 'sphinx_autodoc_annotation', 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', 'sphinxarg.ext', 'sphinx.ext.autosectionlabel']
 extensions = [
     "sphinx_sitemap",
     "plantweb.directive",
@@ -46,6 +46,7 @@
     "sphinxarg.ext",
     "sphinxcontrib_asciinema",
     "sphinxcontrib.details.directive",
+    "sphinx-jsonschema",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -62,7 +63,7 @@
 
 # General information about the project.
 project = "Dfetch"
-copyright = "2021, Dfetch-org"
+copyright = "2021, Dfetch-org"  # pylint: disable=redefined-builtin
 author = "DFetch"
 
 # The version info for the project you're documenting, acts as replacement for
@@ -92,6 +93,12 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+# -- Options for autosectionlabel extension -------------------------------
+autosectionlabel_maxdepth = 3
+
+# Suppress warnings about duplicate labels from argparse directive
+suppress_warnings = ["autosectionlabel.*"]
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

doc/examples.rst

@@ -0,0 +1,14 @@
+.. Dfetch documentation master file
+
+Examples
+============
+
+Real world projects
+-------------------
+
+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.

doc/getting_started.rst

@@ -162,8 +162,10 @@ version.
 
   dfetch diff
 
-This patch file can now be applied automatically by *Dfetch* in next updates.
-Add it to your manifest as shown below.
+A patch file ``ext-test-repo-tag.patch`` is created in the current folder. You can
+place it anywhere you want, as long as it is reachable when running *Dfetch*.
+For this example we keep it in the current folder. This patch file can now be applied
+automatically by *Dfetch* in next updates. Add it to your manifest as shown below.
 
 .. code-block:: yaml
 

doc/index.rst

@@ -35,6 +35,8 @@
    contributing
    changelog
    alternatives
+   examples
+   vendoring
    legal
    internal
 

doc/manifest.rst

@@ -11,3 +11,97 @@ Remotes
 Projects
 --------
 .. automodule:: dfetch.manifest.project
+
+Schema
+------
+
+Below an overview of all possible fields on the manifest. The bold items are mandatory.
+
+.. jsonschema::
+
+    :auto_reference:
+
+    $schema: "http://json-schema.org/draft-07/schema#"
+    type: object
+    required:
+      - manifest
+    properties:
+      manifest:
+        description: Top-level manifest object. See :ref:`Manifest` for details.
+        type: object
+        required:
+          - version
+          - projects
+        properties:
+          version:
+            type: number
+
+          remotes:
+            type: array
+            description: >
+              List of remote sources. See :ref:`Remotes` for details.
+              Each remote must be unique by its name.
+            items:
+              type: object
+              required:
+                - name
+                - url-base
+              properties:
+                name:
+                  type: string
+                  description: A unique name for the remote.
+                url-base:
+                  type: string
+                default:
+                  type: boolean
+              uniqueItems: true
+
+          projects:
+            type: array
+            description: >
+              List of projects to Dfetch. See :ref:`Projects` for details.
+              Each project must be unique by its name.
+            items:
+              type: object
+              required:
+                - name
+              properties:
+                name:
+                  type: string
+                  description: A unique name for the project.
+                dst:
+                  description: Destination path to fetch the project to, see :ref:`Destination` for details.
+                  type: string
+                branch:
+                  type: string
+                tag:
+                  type: string
+                revision:
+                  type: string
+                url:
+                  type: string
+                repo-path:
+                  description: Path within the repository to fetch, see :ref:`Repo-path` for details.
+                  type: string
+                remote:
+                  description: Name of remote to use as base, see :ref:`Remotes` for details.
+                  type: string
+                patch:
+                  type: string
+                  description: Patch to apply after fetching see :ref:`Patch`.
+                vcs:
+                  type: string
+                  description: Version control system used by the project. See :ref:`VCS type` for details.
+                  enum:
+                    - git
+                    - svn
+                src:
+                  type: string
+                  description: >
+                    Source path within the repository to fetch, see :ref:`Source` for details.
+                ignore:
+                  type: array
+                  description: Files to ignore. See :ref:`Ignore` for details.
+                  items:
+                    type: string
+              uniqueItems: true

doc/manual.rst

@@ -139,3 +139,14 @@ Import
 .. asciinema:: asciicasts/import.cast
 
 .. automodule:: dfetch.commands.import_
+
+Overview
+--------
+
+Below an overview of all available commands and their usage. For detailed information
+on each command, please refer to the respective sections above.
+
+.. argparse::
+   :module: dfetch.__main__
+   :func: create_parser
+   :prog: dfetch