Use tags (-t) instead of options (-D) to control docs from CLI

These are already defined when reading conf.py, which means we don’t
need to load extensions after config init (which breaks intersphinx).
Also default to what an installed doc should look like (no code doc,
no install instructions) to make the life of packagers easier.

.github/workflows/deploy_doc_l10n.yml

@@ -47,7 +47,7 @@ jobs:
         poeditor_api_token: ${{ secrets.POEDITOR_API_TOKEN }}
       run: |
         ./scripts/poedit.sh contributors
-        python3 -m sphinx -bhtml docs/ build/sphinx/html
+        python3 -m sphinx -bhtml docs/ build/sphinx/html -t api_doc -t install_instructions
         tar czf pympress-docs.tar.gz -C build/sphinx/html/ .
     - name: Upload
       uses: actions/upload-artifact@v3

docs/conf.py

@@ -41,22 +41,24 @@
     'myst_parser',
 ]
 
-# Whether to include code documentation. Override on the command line with –Dskip_api_doc=1
-skip_api_doc = False
-
-# Extends extensions, if we document the API
-code_doc_extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.todo',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.napoleon',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.coverage',
-    'sphinx.ext.doctest',
-]
-
-# Whether to skip install instructions for included packages
-packaged_docs = False
+# -- TAGS -- to select what gets included in generated docs from the cli.
+# Defaults to whatever is useful for the docs of an installed package.
+
+# Whether to document the code - off by default
+if tags.has('api_doc'):
+    extensions.extend([
+        'sphinx.ext.autodoc',
+        'sphinx.ext.todo',
+        'sphinx.ext.viewcode',
+        'sphinx.ext.napoleon',
+        'sphinx.ext.intersphinx',
+        'sphinx.ext.coverage',
+        'sphinx.ext.doctest',
+    ])
+
+# Whether to include install instructions for included packages - off by default
+if tags.has('install_instructions'):
+    pass
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_template']
@@ -76,33 +78,25 @@ def doc_transform(app, doctree, docname):
             node.parent.remove(node)
 
     # Remove the genindex/modindex section if not relevant
-    if app.builder.name == 'man' or app.config.skip_api_doc:
+    if app.builder.name == 'man' or not tags.has('api_doc'):
         for node in list(doctree.findall(SectionNode)):
             if 'indices-and-tables' in node['ids']:
                 node.parent.remove(node)
 
     # Remove install instructions for docs that are part of a package
-    if app.config.packaged_docs:
+    if not tags.has('install_instructions'):
         for node in list(doctree.findall(SectionNode)):
             if {'installing', 'dependencies', 'packages'} & set(node['ids']):
                 node.parent.remove(node)
 
 
 def doc_remove(app, env, docnames):
     """ Remove API page from list of source files, if we do not build API docs """
-    if app.config.skip_api_doc:
+    if not tags.has('api_doc'):
         env.found_docs.remove('pympress')
         docnames.remove('pympress')
 
 
-def add_extensions(app, config):
-    """ Delayed configuration of extensions to allow enabling or skipping API documentation from the command line """
-    config.html_context['document_api'] = not config.skip_api_doc
-    if not config.skip_api_doc:
-        for ext in code_doc_extensions:
-            app.setup_extension(ext)
-
-
 def setup(app):
     """ Function called by sphinx to setup this documentation """
     # Only use default=False because it is hard to pass falsey things on CLI (i.e. -D...=0 works but not -D...=False)
@@ -111,7 +105,6 @@ def setup(app):
 
     app.connect('env-before-read-docs', doc_remove)
     app.connect('doctree-resolved', doc_transform)
-    app.connect('config-inited', add_extensions)
 
     # When skipping API docs, we get WARNING: toctree contains reference to nonexisting document 'pympress'
     # This could be avoided by modifying the file on 'source-read' events, but not very clean approach
@@ -270,13 +263,22 @@ def guess_epydoc_role(name, uri):
     'Pango': ('https://lazka.github.io/pgi-docs/Pango-1.0', None),
     'GLib': ('https://lazka.github.io/pgi-docs/GLib-2.0', None),
     'GdkX11': ('https://lazka.github.io/pgi-docs/GdkX11-3.0', None),
+    'Gio': ('https://lazka.github.io/pgi-docs/Gio-2.0', None),
     'python': ('https://docs.python.org/{}.{}'.format(*sys.version_info[:2]), None),
     'cairo': ('https://www.cairographics.org/documentation/pycairo/3', None),
     **load_epydoc_as_intersphinx_v2({'vlc': 'https://www.olivieraubert.net/vlc/python-ctypes/doc/'}),
     # No mapping on https://gstreamer.freedesktop.org/documentation/gstreamer/
     'Gst': ('https://lazka.github.io/pgi-docs/Gst-1.0', None),
 }
 
+intersphinx_disabled_reftypes = []
+
+# Don’t sort alphabetically, use order of appearance in code
+autodoc_member_order = 'bysource'
+
+# Don’t put type hints in function signature but put it in the description
+autodoc_typehints = 'description'
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

setup.cfg

@@ -86,7 +86,7 @@ indent_width = 4
 [flake8]
 docstring-convention = google
 max-line-length = 120
-builtins = _, unicode
+builtins = _, unicode, tags
 exclude =
 	.git
 	.eggs