Merge pull request #38 from openSUSE/fix-doc-errors

Fix doc warnings

Author: tomschr

.gitignore

@@ -12,6 +12,8 @@ __pycache__/
 .Python
 /build/
 /docs/build/
+# Sphinx warnings
+/docs/*.log
 develop-eggs/
 /dist/
 downloads/

CHANGELOG.rst

@@ -204,5 +204,3 @@ Removed Features
 ----------------
 
 - Remove tool.setuptools.packages.find
-
-----

changelog.d/38.doc.rst

@@ -0,0 +1,6 @@
+Fix doc warnings from Sphinx
+
+* Have Sphinx warnings written to :file:`docs/sphinx-warnings.log`.
+* Disable ``inherited-members`` option (it creates warnings from a different docstring format).
+* Slightly restructured Reference guide a bit. "Docbuild CLI" is on the top level now, making :file:`modules.rst` obsolete.
+*  Fix some ReST problems in :file:`checks.py` docstrings (mainly missing linebreaks)

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?= -v
+SPHINXOPTS    ?= -v -w sphinx-warnings.log
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
@@ -18,4 +18,4 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-	@echo "Target output: '$(CURDIR)/$(BUILDDIR)/$@'"
+	@echo "Target output: '$(CURDIR)/$(BUILDDIR)/$@'"

docs/source/conf.py

@@ -77,18 +77,18 @@
 autoapi_options = [
     'members',
     # "undoc-members",
-    'inherited-members',
+    # 'inherited-members',
     'show-inheritance',
     'show-module-summary',
-    'imported-members',
+    # 'imported-members',
     'special-members',
     'show-inheritance-diagram',  # needs sphinx.ext.inheritance_diagram & graphviz
     # "private-members",
 ]
 autoapi_keep_files = True
 autodoc_typehints = 'signature'
 autoapi_own_page_level = 'class'
-
+#autoapi_python_use_implicit_namespaces = True
 
 # -- Options for extlinks extension ------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html

docs/source/developer/devel-helpers.rst

@@ -1,8 +1,11 @@
 .. _devel-helpers:
 
+.. start-include-devel-helpers
+
 Helper Tools
 ------------
 
+
 .. include:: ../../../devel/README.rst
    :start-line: 3
 

docs/source/developer/prepare-environment.rst

@@ -42,9 +42,8 @@ The following diagram illustrates the relationship between the main components o
 
 
 
-
 .. include:: devel-helpers.rst
-
+   :start-after: .. start-include-devel-helpers
 
 GitHub CLI
 ----------

docs/source/reference/_autoapi/docbuild/cli/cmd_build/DocBuildContext.rst

@@ -42,48 +42,17 @@ docbuild.cli.cmd_build
 
 
 
-Classes
--------
-
-.. toctree::
-   :hidden:
-
-   /reference/_autoapi/docbuild/cli/cmd_build/Doctype
-   /reference/_autoapi/docbuild/cli/cmd_build/DocBuildContext
-
-.. autoapisummary::
-
-   docbuild.cli.cmd_build.Doctype
-   docbuild.cli.cmd_build.DocBuildContext
-
-
 Functions
 ---------
 
 .. autoapisummary::
 
-   docbuild.cli.cmd_build.validate_doctypes
    docbuild.cli.cmd_build.build
 
 
 Package Contents
 ----------------
 
-.. py:function:: validate_doctypes(ctx: click.Context, param: click.Parameter | None, doctypes: tuple[str, Ellipsis]) -> list[docbuild.models.doctype.Doctype]
-
-   Click callback function to validate a list of doctype strings.
-
-   Each string must conform to the format: PRODUCT/DOCSET@LIFECYCLE/LANGS
-   LANGS can be a single language code, a comma-separated list (no spaces),
-   or '*' for all.
-   Defaults and wildcards (*) are handled.
-
-   :param param: The click parameter that triggered this callback.
-   :param doctypes: A tuple of doctype strings to validate.
-   :return: A list of validated Doctype objects.
-   :raises click.Abort: If any doctype string is invalid, the command is aborted.
-
-
 .. py:function:: build(ctx: click.Context, doctypes: tuple[docbuild.models.doctype.Doctype]) -> None
 
    Subcommand build.

docs/source/reference/_autoapi/docbuild/cli/cmd_build/index.rst

@@ -26,45 +26,12 @@ Functions
 
 .. autoapisummary::
 
-   docbuild.cli.cmd_repo.clone
-   docbuild.cli.cmd_repo.cmd_dir
-   docbuild.cli.cmd_repo.cmd_list
    docbuild.cli.cmd_repo.repo
 
 
 Package Contents
 ----------------
 
-.. py:function:: clone(ctx: click.Context, repos: tuple[str, Ellipsis]) -> None
-
-   Clone repositories into permanent directory.
-
-   :param repos: A tuple of repository selectors. If empty, all repos are cloned.
-   :param ctx: The Click context object.
-
-
-.. py:function:: cmd_dir(ctx: click.Context) -> None
-
-   Show the directory path for permanent repositories.
-
-   Outputs the path to the repository directory defined
-   in the environment configuration.
-
-   :param ctx: The Click context object.
-
-
-.. py:function:: cmd_list(ctx: click.Context) -> None
-
-   List the available permanent repositories.
-
-   Outputs the directory names of all repositories defined in the
-   environment configuration.
-   If no repositories are defined, it outputs a message indicating that
-   no repositories are available.
-
-   :param ctx: The Click context object.
-
-
 .. py:function:: repo(ctx: click.Context) -> None
 
    Subcommand to validate XML configuration files.