Merge pull request #975 from carmenbianca/improve-docs

Improvements to docs; make manpages

.github/workflows/test.yaml

@@ -128,7 +128,7 @@ jobs:
       - name: Install dependencies
         run: |
           pip install poetry~=1.2.0
-          pip install -r docs/requirements.txt
+          poetry install --no-interaction --only main,docs
       - name: Create docs with Sphinx
         run: |
-          make docs-ci
+          make docs

.gitignore

@@ -152,7 +152,7 @@ po/reuse.pot
 docs/api/
 docs/history.md
 docs/readme.md
-docs/contributing.md
+docs/contribute.md
 prof/
 
 # Nix-related

.readthedocs.yaml

@@ -5,16 +5,15 @@
 version: 2
 
 build:
-  # This should mirror the configuration in ./.github/workflows/pythonpackage.yaml
-  os: "ubuntu-20.04"
+  # This should mirror the configuration in ./.github/workflows/test.yaml
+  os: ubuntu-22.04
   tools:
     python: "3.8"
-
-python:
-  install:
-    # This file is generated with poetry as follows:
-    # poetry export --with docs --without-hashes >docs/requirements-docs.txt
-    - requirements: docs/requirements.txt
+  jobs:
+    post_create_environment:
+      - pip install poetry
+    post_install:
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs
 
 sphinx:
   configuration: docs/conf.py

CHANGELOG.md

@@ -42,6 +42,8 @@ CLI command and its behaviour. There are no guarantees of stability for the
 
 ### Added
 
+- Manpages added for all `reuse` commands. Distribution maintainers might wish
+  to distribute the (Sphinx-built) manpages. (#975)
 - More file types are recognised:
   - Assembler (`.asm`) (#928)
   - GraphQL (`.graphqls`, `.gqls`) (#930)
@@ -72,6 +74,8 @@ CLI command and its behaviour. There are no guarantees of stability for the
   (#949)
 - The datetime value for `Created:` was wrongly formatted since 3.0.0. It now
   returns a correctly formatted ISO 8601 date again. (#952)
+- Repaired the behaviour of `reuse download` where being inside of a LICENSES/
+  directory should not create a deeper LICENSES/LICENSES/ directory. (#975)
 - Support annotating a file that contains only a shebang. (#965)
 
 ### Security

Makefile

@@ -57,12 +57,7 @@ lint-third-party: ## Lint selected third-party repositories to compare with expe
 
 .PHONY: docs
 docs: clean-docs ## generate Sphinx HTML documentation, including API docs
-	poetry export --with docs --without-hashes >docs/requirements.txt
-	$(MAKE) -C docs html
-
-.PHONY: docs-ci
-docs-ci: ## generate Sphinx HTML documentation, including API docs without dependency file generation (for CI)
-	$(MAKE) -C docs html
+	$(MAKE) -C docs html man
 
 .PHONY: dist
 dist: clean-build clean-pyc clean-docs ## builds source and wheel package

README.md

@@ -29,7 +29,7 @@ recommendations.
 - [Usage](#usage)
 - [Maintainers](#maintainers)
 - [Contributing](#contributing)
-- [License](#license)
+- [Licensing](#licensing)
 
 ## Background
 
@@ -258,6 +258,9 @@ an error.
 ## Maintainers
 
 - Carmen Bianca Bakker <[email protected]>
+
+### Former maintainers
+
 - Max Mehl <[email protected]>
 - Linus Sehn <[email protected]>
 
@@ -276,7 +279,7 @@ discussion and support related to the project.
 You can find the full contribution guidelines at
 <https://reuse.readthedocs.io/en/latest/contributing.html>.
 
-## License
+## Licensing
 
 This work is licensed under multiple licences. Because keeping this section
 up-to-date is challenging, here is a brief summary as of April 2024:

docs/Makefile

@@ -3,9 +3,8 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = reuse
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 

docs/conf.py

@@ -2,75 +2,31 @@
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-# reuse documentation build configuration file, created by
-# sphinx-quickstart on Wed Nov  1 14:41:46 2017.
+# Configuration file for the Sphinx documentation builder.
 #
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
 
-# 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
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
 import os
-import sys
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as get_version
+from pathlib import Path
 from shutil import copyfile
 
-sys.path.insert(0, os.path.abspath("../src/"))
-
+DOCS_DIR = Path(os.path.dirname(__file__))
+ROOT_DIR = (DOCS_DIR / "..").resolve()
 
-# -- General configuration ------------------------------------------------
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = [
-    "recommonmark",
-    "sphinx.ext.autodoc",
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.viewcode",
-    "sphinx.ext.napoleon",
-    "sphinxcontrib.apidoc",
-]
-
-apidoc_module_dir = "../src/reuse"
-# apidoc_output_dir = "api"
-# apidoc_excluded_paths = []
-apidoc_separate_modules = True
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-#
-# source_suffix = ['.rst', '.md']
-source_suffix = [".rst", ".txt", ".md"]
-
-# The master toctree document.
-master_doc = "index"
-
-# General information about the project.
 project = "reuse"
-copyright = "2017-2023, Free Software Foundation Europe. CC-BY-SA-4.0"
+copyright = "2017, Free Software Foundation Europe. CC-BY-SA-4.0"
 author = "Free Software Foundation Europe"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
-
 try:
     # The full version, including alpha/beta/rc tags.
     release = get_version("reuse")
@@ -87,110 +43,106 @@
 # Usually you set "language" from the command line for these cases.
 language = "en"
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This patterns also effect to html_static_path and html_extra_path
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "sphinxcontrib.apidoc",
+]
+
+templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
+# -- Extensions configuration ------------------------------------------------
+
+apidoc_module_dir = str(ROOT_DIR / "src/reuse")
+# apidoc_output_dir = "api"
+# apidoc_excluded_paths = []
+apidoc_separate_modules = True
+apidoc_toc_file = False
+apidoc_extra_args = ["--maxdepth", "2"]
 
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
+autodoc_member_order = "bysource"
 
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
 
-# -- Options for HTML output ----------------------------------------------
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
 html_theme = "furo"
 html_logo = "reuse-r-only.svg"
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#
-# html_theme_options = {}
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
-# -- Options for HTMLHelp output ------------------------------------------
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = "reusedoc"
-
-
-# -- Options for LaTeX output ---------------------------------------------
-
-latex_elements: dict = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-latex_documents = [
+# -- Options for man output --------------------------------------------------
+man_pages = [
     (
-        master_doc,
-        "reuse.tex",
-        "reuse Documentation",
+        "man/reuse",
+        "reuse",
+        "A tool for compliance with the REUSE recommendations",
         "Free Software Foundation Europe",
-        "manual",
-    )
-]
-
-
-# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "reuse", "reuse Documentation", [author], 1)]
-
-
-# -- Options for Texinfo output -------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-texinfo_documents = [
+        1,
+    ),
     (
-        master_doc,
-        "reuse",
-        "reuse Documentation",
-        author,
-        "reuse",
-        "One line description of project.",
-        "Miscellaneous",
-    )
+        "man/reuse-annotate",
+        "reuse-annotate",
+        "Add REUSE information to files",
+        "Free Software Foundation Europe",
+        1,
+    ),
+    (
+        "man/reuse-convert-dep5",
+        "reuse-convert-dep5",
+        "Convert .reuse/dep5 to REUSE.toml",
+        "Free Software Foundation Europe",
+        1,
+    ),
+    (
+        "man/reuse-download",
+        "reuse-download",
+        "Download license files",
+        "Free Software Foundation Europe",
+        1,
+    ),
+    (
+        "man/reuse-lint",
+        "reuse-lint",
+        "Verify whether a project is compliant with the REUSE Specification",
+        "Free Software Foundation Europe",
+        1,
+    ),
+    (
+        "man/reuse-spdx",
+        "reuse-spdx",
+        "Generate SPDX bill of materials",
+        "Free Software Foundation Europe",
+        1,
+    ),
+    (
+        "man/reuse-supported-licenses",
+        "reuse-supported-licenses",
+        "Print a list of supported licenses",
+        "Free Software Foundation Europe",
+        1,
+    ),
 ]
 
-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)}
+# -- Custom ------------------------------------------------------------------
 
 
 def copy_markdown(_):
     """Copy the markdown files from the root of the project into the docs/
     directory.
     """
-    copyfile("../README.md", "readme.md")
-    copyfile("../CHANGELOG.md", "history.md")
-    copyfile("../CONTRIBUTING.md", "contributing.md")
+    copyfile(ROOT_DIR / "README.md", DOCS_DIR / "readme.md")
+    copyfile(ROOT_DIR / "CHANGELOG.md", DOCS_DIR / "history.md")
+    # this used to be renamed to 'contributing.md', but this caused a conflict
+    # with the ToC in the README.
+    copyfile(ROOT_DIR / "CONTRIBUTING.md", DOCS_DIR / "contribute.md")
 
 
 def setup(app):