create a mkdocs docsite

Create a docsite with rendered manpages, changelogs, and Python API
documentation using mkdocs and mkdocstrings. Add a doc extra in
pyproject.toml and a mkdocs nox target. Reformat NEWS.md to fit in the
docsite.

.gitignore

@@ -14,3 +14,5 @@ fedrq.1
 /doc/fedrq*.tar.gz
 /venv/
 FRAG.md
+/doc/fedrq?.md
+/site/

NEWS.md

@@ -1,12 +1,12 @@
-fedrq 0.5.0
-=============
+NEWS
+=====
 
-New dependencies
-----------------
+## fedrq 0.5.0
+
+### New dependencies
 - requests
 
-Highlighted examples
-----------------
+### Highlighted examples
 
 Find the latest version of `fedrq` available in the gotmax23/fedrq-dev copr. No extra configuration is required!
 
@@ -34,8 +34,7 @@ mpv-libs.x86_64 : updates
 [...]
 ```
 
-Changed
---------
+### Changed
 - Release: use releasever as cache directory key (https://todo.sr.ht/~gotmax23/fedrq/18)
 - change format of copr_chroot_fmt in ReleaseConfig
 - config: improve Release repository loading.
@@ -51,8 +50,7 @@ Changed
   ([More details](https://git.sr.ht/~gotmax23/fedrq/commit/68fd6d31dc64bdffc3f3867992eb1d82ff0a9f03))
 - release.toml: update for new reoo loading API
 
-Added
-------
+### Added
 - Add centos-stream8 release configuration
 - Add whatobsoletes subcommand
 - formatters: add full_nevra formatter
@@ -73,12 +71,10 @@ fedrq.spec:
 - include api_examples in %doc
 - explicitly require python3-rpm
 
-Fixed
--------
+### Fixed
 - releases.toml: Fix typo in epel_next release def
 
-Testing and development workflow
---------------------------------
+### Testing and development workflow
 - nox: remove fclogr venv workarounds
 - ruff: enable unused-arguments rules
 - improve test_subpkgs_match2 integration test
@@ -86,13 +82,11 @@ Testing and development workflow
 - test Release._copr_repo() formatting
 - nox publish: install all deps into the venv
 
-fedrq 0.4.1
-============
+## fedrq 0.4.1
 
 This is a minor bugfix release that accounts for breaking libdnf5 API changes.
 
-Fixed
-------
+### Fixed
 
 - BaseMaker: make compatible with libdnf5 changes. libdnf5 [changed its
   configuration API](https://github.com/rpm-software-management/dnf5/pull/327)
@@ -100,31 +94,26 @@ Fixed
   compatibility with both API versions.
 - Clarify explanatory comments in api_examples
 
-Added
-------
+### Added
 
 - Add location attr to PackageCompat and formatters.
   Example: `fedrq pkgs ansible -Flocation`
 
-Testing and Dev Workflow
-------------------------
+### Testing and Dev Workflow
 
 - Add nox targets to release fedrq
 
 
-fedrq 0.4.0
-===========
+## fedrq 0.4.0
 
-Changed
---------
+### Changed
 
 - fedrq is now in beta.
 - fedrq.spec: Always Require distribution-gpg-keys
 - Command: simplify smartcache and load_filelists
 - change logging format to include line numbers
 
-Added
------
+### Added
 
 CLI:
 
@@ -146,25 +135,21 @@ API:
 - BaseMaker and Repoquery: add `backend` property to access the current backend module
 - libdnf5: add `config_loaded` param to BaseMaker
 
-Tests
-------
+### Tests
 
 - .builds f36: don't run unit tests twice
 - Remove lint.sh in favor of nox and switch to ruff
 - Fix ruff linting errors
 
-New Contributors
------------------
+### New Contributors
 
 - Thanks to Alfredo Moralejo (~amoralej) for contributing the `plainwithrepo`
   formatter.
 
 
-fedrq 0.3.0
-============
+## fedrq 0.3.0
 
-Changed
----------
+### Changed
 - Get rid of importlib_resources on Python 3.9. We can use the stdlib version.
 - Stop excluding files from the sdist.
 - Abstract dnf code into backends. (INTERNAL API)
@@ -176,8 +161,7 @@ Changed
     `fedrq.backends`.
 - Make loading filelists optional.
 
-Added
--------
+### Added
 - **Add a libdnf5 backend.**
     - Use *-b* / *--backend* or `backend` in the config file to explicitly
       choose a backend. Otherwise, the default backend (currently dnf) will be
@@ -189,18 +173,15 @@ Added
   This provides more flexibility than `fedrq.repoquery` which is now a shim
   module and is the recommended approach. (INTERNAL API)
 
-Fixed
--------
+### Fixed
 - whatrequires -P: don't resolve SRPM names
 - Repoquery: ensure all Provides are resolved
 
-Documentation
--------------
+### Documentation
 - fedrq.1: add --backend and --filelists.
 - fedrq.5: document `backend` and `filelist` config options
 
-Testing
----------
+### Testing
 - .builds: Use fclogr main branch
 - Fix Copr dev builds
 - .builds: Run rpmlint
@@ -213,26 +194,22 @@ Testing
 - nox: add testa target to test both backends at once
 
 
-fedrq 0.2.0
-============
+## fedrq 0.2.0
 
-Changed
--------
+### Changed
 - Use $XDG_CACHE_HOME/fedrq to store instead of /var/tmp to store
   smartcache. This removes `fedrq.cli.Command.v_cachedir()`,
   `fedrq._utils.make_cachedir()`, and `fedrq.config.SMARTCACHE_BASEDIR`;
   they're no longer needed after this change.
 
-Fixed
------
+### Fixed
 - Fix EL 9 and Python 3.9 compatibility
     - Add fallback Fedora repository definitions.
     - Use `importlib_resources` backport.
     - Don't use @staticmethod as a decorator. This doesn't work with
       Python 3.9.
 
-Dev Changes
------------
+### Dev Changes
 - Remove unnecessary `argparse.ArgumentParser.parse_args` workaround
 - Fix importlib_resources.abc.Traversable type checking
 - Test and lint on EPEL 9 and Fedora 36 in CI
@@ -240,11 +217,9 @@ Dev Changes
 - Ditch rpmautospec in favor of fclogr
 
 
-fedrq 0.1.0
-============
+## fedrq 0.1.0
 
-Summary
---------
+### Summary
 - New JSON formatter
 - `fedrq subpkgs --match` to filter `fedrq subpkgs` output packages
 - Add smartcache CLI flag and config option to avoid clearing the system
@@ -254,8 +229,7 @@ Summary
 - More test coverage
 - Docs improvements
 
-Bugfixes
-----------
+### Bugfixes
 - Tweak README wording
 - Command: Fix configuration error handling
 - Make _v_fatal_error and _v_handle_errors DRY
@@ -263,8 +237,7 @@ Bugfixes
 - Fix cli.Subpkgs v_arch() method
 - Add more config validation
 
-Tests
-------
+### Tests
 - Reorganize tests
 - tests: Don't hardcode x86_64
 - Add basic `fedrq pkgs` integration test
@@ -274,8 +247,7 @@ Tests
 - formatters: Add tests and improve error handling
 - Test smartcache config option
 
-New Features
--------------
+### New Features
 - Add initial --smartcache implementation
 - Allow setting smartcache in config file and enable it by default
 - formatters: Add missing attrs
@@ -283,8 +255,7 @@ New Features
 - subpkgs: Add --match option
 - Add fedrq(5) manpage
 
-Breaking API Changes
----------------------
+### Breaking API Changes
 *Note that fedrq's API is currently unstable and not intended for
 outside usage.*
 
@@ -293,8 +264,7 @@ outside usage.*
 - Reimplement FormatterContainer (private API)
 
 
-fedrq 0.0.2
-===========
+## fedrq 0.0.2
 
 - pyproject.toml: Add project.urls
 - pyproject.toml: Change Development Status to Alpha
@@ -305,6 +275,17 @@ fedrq 0.0.2
 - Add fedrq-dev copr
 
 
+## fedrq 0.0.1
+Initial release
+rls
+- pyproject.toml: Change Development Status to Alpha
+- Truncate RPM changelog
+- Exclude rpmautospec `changelog` from sdist
+- fedrq.spec: Workaround F36's old flit-core
+- fedrq.spec: Remove unnecessary rpmdevtools BR
+- Add fedrq-dev copr
+
+
 fedrq 0.0.1
 =======
 Initial release

README.md

@@ -23,6 +23,8 @@ more user friendly interface than `dnf repoquery` for certain common tasks.
 
 [![copr build status][badge-copr-dev]][link-copr-dev] (dev)
 
+[![docsite][badge-docsite]][link-docsite]
+
 [![fedrq on sr.ht][badge-hub]][link-hub]
 
 [![fedrq on git.sr.ht][badge-repo]][link-repo]
@@ -67,20 +69,17 @@ API's main purpose is repoquerying, but you can use the fedrq functionality
 you'd like and then access the underlying dnf Base object to preform other
 tasks if needed.
 
-See [API.md] for more information. See [api-examples] for some example code. As
-always, direct any feedback, questions, or issues to the mailing list (see ##
-Contributing).
+See the [API Summary] on the docsite for more information. See [api-examples]
+for some example code. As always, direct any feedback, questions, or issues to
+the mailing list (see ## Contributing).
+
+[API Summary]: https://fedrq.gtmx.me/API/Summary/
 
 
 ## Documentaion
 
-See [fedrq(1)][fedrq1] ([source][fedrq1-source]) for the CLI interface
-and [fedrq(5)][fedrq5] ([source][fedrq5-source]) for the config file format.
-
-[fedrq1]: https://gotmax23.srht.site/fedrq/fedrq.1.html
-[fedrq1-source]: https://git.sr.ht/~gotmax23/fedrq/tree/main/doc/fedrq.1.scd
-[fedrq5]: https://gotmax23.srht.site/fedrq/fedrq.5.html
-[fedrq5-source]: https://git.sr.ht/~gotmax23/fedrq/tree/main/doc/fedrq.5.scd
+See our new [docsite][link-docsite] for rendered manpages, changelogs, and
+Python API documentation.
 
 
 ## Contributing
@@ -131,3 +130,5 @@ SPDX-License-Identifier: GPL-2.0-or-later AND Unlicense AND MIT AND PSF-2.0
 [link-copr]: https://copr.fedorainfracloud.org/coprs/gotmax23/fedrq/
 [badge-copr-dev]: https://copr.fedorainfracloud.org/coprs/gotmax23/fedrq-dev/package/fedrq/status_image/last_build.png
 [link-copr-dev]: https://copr.fedorainfracloud.org/coprs/gotmax23/fedrq-dev/
+[badge-docsite]: https://img.shields.io/badge/docs-fedrq-blue?style=for-the-badge&logo=readthedocs
+[link-docsite]: https://fedrq.gtmx.me

doc/API/Summary.md

@@ -22,34 +22,34 @@ related functionality. The main primitives are:
 
 ### BaseMaker
 
-**Base class**: `fedrq.backends.base.BaseMakerBase`
+**Base class**: [`fedrq.backends.base.BaseMakerBase`][fedrq.backends.base.BaseMakerBase]
 
-**dnf backend:** `fedrq.backends.dnf.backend.BaseMaker`
+**dnf backend:** [`fedrq.backends.dnf.backend.BaseMaker`][fedrq.backends.dnf.backend.BaseMaker]
 
-**libdnf5 backend:** `fedrq.backends.libdnf5.backend.BaseMaker`
+**libdnf5 backend:** [`fedrq.backends.libdnf5.backend.BaseMaker`][fedrq.backends.libdnf5.backend.BaseMaker]
 
 `BaseMaker` allows configuring a dnf Base session and loading repositories.
 
 ### Repoquery
 
-**Base class**: `fedrq.backends.base.RepoqueryBase`
+**Base class**: [`fedrq.backends.base.RepoqueryBase`][fedrq.backends.base.RepoqueryBase]
 
-**dnf backend:** `fedrq.backends.dnf.backend.Repoquery`
+**dnf backend:** [`fedrq.backends.dnf.backend.Repoquery`][fedrq.backends.dnf.backend.Repoquery]
 
-**libdnf5 backend:** `fedrq.backends.libdnf5.backend.Repoquery`
+**libdnf5 backend:** [`fedrq.backends.libdnf5.backend.Repoquery`][fedrq.backends.libdnf5.backend.Repoquery]
 
-`BaseMaker` takes an initialized Base object (see `BaseMaker`) and allows
+`Repoquery` takes an initialized Base object (see `BaseMaker`) and allows
 preforming a large range of queries. Most of its methods return
 `PackageQueryCompat` or `PackageCompat` objects.
 
 
 ### PackageQueryCompat
 
-**Protocol:** `fedrq.backends.base.PackageCompat`
+**Protocol:** [`fedrq.backends.base.PackageQueryCompat`][fedrq.backends.base.PackageQueryCompat]
 
-**dnf backend:** `fedrq.backends.dnf.backend.PackageQuery` -> `hawkey.Query`
+**dnf backend:** [`fedrq.backends.dnf.backend.PackageQuery`][fedrq.backends.dnf.backend.PackageQuery] -> `hawkey.Query`
 
-**libdnf5 backend:** `fedrq.backends.libdnf5.backend.Package`
+**libdnf5 backend:** [`fedrq.backends.libdnf5.backend.Package`](fedrq.backends.libdnf5.backend.Package)
 (`libdnf5.package.Package` subclass)
 
 PackageQueryCompat is a set like object of PackageCompat objects. It contains
@@ -63,11 +63,11 @@ access these through the Repoquery class.
 ### PackageCompat
 
 
-**Protocol:** `fedrq.backends.base.PackageCompat`
+**Protocol:** [`fedrq.backends.base.PackageCompat`][fedrq.backends.base.PackageCompat]
 
-**dnf backend:** `fedrq.backends.dnf.backend.Package` -> `dnf.package.Package`
+**dnf backend:** [`fedrq.backends.dnf.backend.Package`][fedrq.backends.dnf.backend.Package] -> `dnf.package.Package`
 
-**libdnf5 backend:** `fedrq.backends.libdnf5.backend.Package`
+**libdnf5 backend:** [`fedrq.backends.libdnf5.backend.Package`][fedrq.backends.libdnf5.backend.Package]
 (`libdnf5.package.Package` subclass)
 
 - `fedrq.backends.libdnf5.backend.Package` - subclass of `libdnf5.rpm.Package`
@@ -81,13 +81,13 @@ access these through the Repoquery class.
     Importing `fedrq.backends.libdnf5.backend` registers the `Package` subclass
     so PackageQuery contains our subclass.
 
-## fedrq.config
+## [`fedrq.config`][fedrq.config]
 
 Most of the code here should not be called directly. Use `get_config()` to load
 the configuration from the filesystem. Create an `RQConfig` object manually if
 you must.
 
-This exaple shows how to load the configuration and preform a basic query.
+This example shows how to load the configuration and preform a basic query.
 
 ``` python
 # SPDX-License-Identifier: Unlicense

doc/API/backends/base.md

@@ -0,0 +1,9 @@
+<!--
+Copyright (C) 2023 Maxwell G <maxwell@gtmx.me>
+
+SPDX-License-Identifier: GPL-2.0-or-later
+-->
+
+# fedrq.backends.base
+
+::: fedrq.backends.base

doc/API/backends/dnf.md

@@ -0,0 +1,9 @@
+<!--
+Copyright (C) 2023 Maxwell G <maxwell@gtmx.me>
+
+SPDX-License-Identifier: GPL-2.0-or-later
+-->
+
+# fedrq.backends.dnf.backend
+
+::: fedrq.backends.dnf.backend

doc/API/backends/libdnf5.md

@@ -0,0 +1,18 @@
+<!--
+Copyright (C) 2023 Maxwell G <maxwell@gtmx.me>
+
+SPDX-License-Identifier: GPL-2.0-or-later
+-->
+
+# fedrq.backends.libdnf5.backend
+
+::: fedrq.backends.libdnf5.backend
+    options:
+        members:
+            - BACKEND
+            - BaseMaker
+            - Package
+            - PackageQuery
+            - RepoError
+            - Repoquery
+            - get_releasever

doc/API/config.md

@@ -0,0 +1,9 @@
+<!--
+Copyright (C) 2023 Maxwell G <maxwell@gtmx.me>
+
+SPDX-License-Identifier: GPL-2.0-or-later
+-->
+
+# fedrq.config
+
+::: fedrq.config

doc/API/release_repo.md

@@ -0,0 +1,9 @@
+<!--
+Copyright (C) 2023 Maxwell G <maxwell@gtmx.me>
+
+SPDX-License-Identifier: GPL-2.0-or-later
+-->
+
+# fedrq.release_repo
+
+::: fedrq.release_repo

doc/News.md

@@ -0,0 +1 @@
+../NEWS.md

doc/index.md

@@ -0,0 +1 @@
+../README.md

fedrq.spec

@@ -79,7 +79,7 @@ FEDRQ_BACKEND=libdnf5 %pytest -v -m "not no_rpm_mock"
 %files -f %{pyproject_files}
 # Licenses are included in the wheel
 %license %{_licensedir}/fedrq/
-%doc README.md CONTRIBUTING.md NEWS.md doc/API.md contrib/api_examples
+%doc README.md CONTRIBUTING.md NEWS.md contrib/api_examples
 %{_bindir}/fedrq*
 %{_mandir}/man1/fedrq.1*
 %{_mandir}/man5/fedrq.5*

mkdocs.yml

@@ -0,0 +1,75 @@
+---
+# Copyright (C) 2023 Maxwell G <maxwell@gtmx.me>
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+site_name: fedrq
+repo_url: "https://git.sr.ht/~gotmax23/fedrq/tree/main"
+edit_uri: "item/doc"
+repo_name: "sr.ht/~gotmax23/fedrq"
+docs_dir: doc
+theme:
+  name: material
+  icon:
+    repo: "fontawesome/regular/circle"
+    edit: "material/eye"
+  features:
+    - content.code.copy
+    - content.action.edit
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      primary: pink
+      accent: pink
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: pink
+      accent: pink
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+markdown_extensions:
+  - toc:
+      permalink: true
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.superfences
+plugins:
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          options:
+            docstring_style: sphinx
+            show_if_no_docstring: true
+            merge_init_into_class: true
+            filters: ["!^__?", "!LOG", "!logger"]
+          paths:
+            - src/
+          import:
+            - https://docs.python.org/3/objects.inv
+  - exclude:
+      glob:
+        - "*.tar.gz"
+        - "fedrq.1*"
+        - "fedrq.5*"
+watch:
+  - "README.md"
+  - "NEWS.md"
+  - "src/fedrq"
+nav:
+  - Home: index.md
+  - News.md
+  - man fedrq: fedrq1.md
+  - man 5 fedrq: fedrq5.md
+  - API:
+    - API/Summary.md
+    - "fedrq.config": API/config.md
+    # Undocumented
+    # - "fedrq.release_repo": API/release_repo.md
+    - "fedrq.backends":
+      - "fedrq.backends.base": API/backends/base.md
+      - "fedrq.backends.dnf.backend": API/backends/dnf.md
+      - "fedrq.backends.libdnf5.backend": API/backends/libdnf5.md

noxfile.py

@@ -250,3 +250,20 @@ def bump(session: nox.Session):
 def publish(session: nox.Session):
     install(session, "copr", "dbus-python", "flit", "keyring", "twine")
     session.run("bash", "-x", "contrib/publish.sh", *session.posargs)
+
+
+@nox.session
+def mkdocs(session: nox.Session):
+    install(session, "-e", ".[doc]")
+    for i in ("1", "5"):
+        # ruff: noqa: W605
+        session.run(
+            "sh",
+            "-c",
+            f"scd2html < doc/fedrq.{i}.scd"
+            "| pandoc --from html --to markdown_strict"
+            "| sed -e '/:::/d' -e 's| \[¶\].*||'"
+            f"> doc/fedrq{i}.md",
+            external=True,
+        )
+    session.run("mkdocs", *session.posargs)

pyproject.toml

@@ -56,6 +56,12 @@ test = [
     "pytest-mock",
     "tomli-w",
 ]
+doc = [
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocstrings[python]>=0.18",
+    "mkdocs-exclude",
+]
 dev = [
     "fedrq[test]",
     "fedrq[lint]",

src/fedrq/backends/base.py

@@ -417,13 +417,14 @@ class RepoqueryBase(abc.ABC):
         """
         Filter a query's architectures in place and return it.
         It includes a little more functionality than query.filterm(arch=...).
-            - When arch is None, the query is left untouched.
-            - If arch equals 'notsrc', all src and multilib packages are
-              excluded.
-            - If arch equals 'arched', all noarch, multilib, and source
-              packages are excluded.
-            - Otherwise, arch is passed to query.filterm(arch=...) and no other
-              validation is preformed.
+
+        - When arch is None, the query is left untouched.
+        - If arch equals 'notsrc', all src and multilib packages are
+          excluded.
+        - If arch equals 'arched', all noarch, multilib, and source
+          packages are excluded.
+        - Otherwise, arch is passed to query.filterm(arch=...) and no other
+          validation is preformed.
         """
         if not arch:
             return query
@@ -440,13 +441,14 @@ class RepoqueryBase(abc.ABC):
         """
         Filter a query's architectures and return it.
         It includes a little more functionality than query.filter(arch=...).
-            - When arch is None, the query is left untouched.
-            - If arch equals 'notsrc', all src and multilib packages are
-              excluded.
-            - If arch equals 'arched', all noarch, multilib, and source
-              packages are excluded.
-            - Otherwise, arch is passed to query.filterm(arch=...) and no other
-              validation is preformed.
+
+        - When arch is None, the query is left untouched.
+        - If arch equals 'notsrc', all src and multilib packages are
+          excluded.
+        - If arch equals 'arched', all noarch, multilib, and source
+          packages are excluded.
+        - Otherwise, arch is passed to query.filterm(arch=...) and no other
+          validation is preformed.
         """
         if not arch:
             return query
@@ -500,7 +502,6 @@ class RepoqueryBase(abc.ABC):
         by {packages}.
 
         :param package: A :class:`PackageQueryCompat` containing source packages
-        :param package: Set this to filter out subpackages with a specific arch
         """
         arch = kwargs.get("arch")
         if arch == "src":
@@ -529,7 +530,10 @@ class RepoqueryBase(abc.ABC):
 
 class BackendMod(Protocol):
     """
-    Protocol for a backend module
+    Protocol for a fedrq backend module.
+    Each backend module (e.g.
+    [`fedrq.backends.dnf.backend`][fedrq.backends.dnf.backend])
+    implements this interface.
     """
 
     BACKEND: str

src/fedrq/backends/dnf/backend.py

@@ -1,6 +1,12 @@
 # SPDX-FileCopyrightText: 2023 Maxwell G <gotmax@e.email>
 # SPDX-License-Identifier: GPL-2.0-or-later
 
+"""
+This module contains a fedrq backend (i.e. an implementation of the
+[`fedrq.backends.base.BackendMod`][fedrq.backends.base.BackendMod] interface)
+that uses the dnf Python bindings.
+"""
+
 from __future__ import annotations
 
 import logging

src/fedrq/backends/libdnf5/backend.py

@@ -1,6 +1,12 @@
 # SPDX-FileCopyrightText: 2023 Maxwell G <gotmax@e.email>
 # SPDX-License-Identifier: GPL-2.0-or-later
 
+"""
+This module contains a fedrq backend (i.e. an implementation of the
+[`fedrq.backends.base.BackendMod`][fedrq.backends.base.BackendMod] interface)
+that uses the libdnf5 Python bindings.
+"""
+
 from __future__ import annotations
 
 import functools

src/fedrq/config.py

@@ -1,6 +1,11 @@
 # SPDX-FileCopyrightText: 2022 Maxwell G <gotmax@e.email>
 # SPDX-License-Identifier: GPL-2.0-or-later
 
+"""
+This module houses code to load configuration from the filesystem and validate
+it.
+"""
+
 from __future__ import annotations
 
 import importlib.resources as importlib_resources