Inspecting the scope of API documentation with Sphinx intersphinx

[sr-murthy]

These are just observations on the Sphinx-style objects inventory for PDM documentation. The objects referred to are all the publicly documented members in the API Reference, as well as sections of the Development guide on pytest fixtures.

The object inventory can be "inspected / verified" with the Sphinx intersphinx extension:

$ python -m sphinx.ext.intersphinx 'https://pdm.fming.dev/latest/objects.inv'
py:attr
    pdm.core.Core.state                                                              : reference/api/#pdm.core.Core.state
    pdm.project.core.Project.config                                                  : reference/api/#pdm.project.core.Project.config
    pdm.project.core.Project.default_source                                          : reference/api/#pdm.project.core.Project.default_source
    pdm.project.core.Project.project_config                                          : reference/api/#pdm.project.core.Project.project_config
    pdm.pytest.RunResult.exception                                                   : dev/fixtures/#pdm.pytest.RunResult.exception
    pdm.pytest.RunResult.exit_code                                                   : dev/fixtures/#pdm.pytest.RunResult.exit_code
    pdm.pytest.RunResult.output                                                      : dev/fixtures/#pdm.pytest.RunResult.output
    pdm.pytest.RunResult.outputs                                                     : dev/fixtures/#pdm.pytest.RunResult.outputs
    pdm.pytest.RunResult.stderr                                                      : dev/fixtures/#pdm.pytest.RunResult.stderr
    pdm.pytest.RunResult.stdout                                                      : dev/fixtures/#pdm.pytest.RunResult.stdout
py:class
    pdm.core.Core                                                                    : reference/api/#pdm.core.Core
    pdm.core.Project                                                                 : reference/api/#pdm.core.Project
    pdm.project.Project                                                              : reference/api/#pdm.core.Project
    pdm.project.core.Project                                                         : reference/api/#pdm.core.Project
    pdm.pytest.Core                                                                  : reference/api/#pdm.core.Core
    pdm.pytest.Distribution                                                          : dev/fixtures/#pdm.pytest.Distribution
    pdm.pytest.LocalIndexTransport                                                   : dev/fixtures/#pdm.pytest.LocalIndexTransport
    pdm.pytest.MockWorkingSet                                                        : dev/fixtures/#pdm.pytest.MockWorkingSet
    pdm.pytest.PDMCallable                                                           : dev/fixtures/#pdm.pytest.PDMCallable
    pdm.pytest.Project                                                               : reference/api/#pdm.core.Project
    pdm.pytest.RunResult                                                             : dev/fixtures/#pdm.pytest.RunResult
    pdm.pytest.TestRepository                                                        : dev/fixtures/#pdm.pytest.TestRepository
py:data
    pdm.pytest.IndexMap                                                              : dev/fixtures/#pdm.pytest.IndexMap
    pdm.pytest.IndexOverrides                                                        : dev/fixtures/#pdm.pytest.IndexOverrides
    pdm.pytest.IndexesDefinition                                                     : dev/fixtures/#pdm.pytest.IndexesDefinition
    pdm.signals.post_build                                                           : reference/api/#pdm.signals.post_build
    pdm.signals.post_init                                                            : reference/api/#pdm.signals.post_init
    pdm.signals.post_install                                                         : reference/api/#pdm.signals.post_install
    pdm.signals.post_lock                                                            : reference/api/#pdm.signals.post_lock
    pdm.signals.post_publish                                                         : reference/api/#pdm.signals.post_publish
    pdm.signals.post_run                                                             : reference/api/#pdm.signals.post_run
    pdm.signals.post_script                                                          : reference/api/#pdm.signals.post_script
    pdm.signals.post_use                                                             : reference/api/#pdm.signals.post_use
    pdm.signals.pre_build                                                            : reference/api/#pdm.signals.pre_build
    pdm.signals.pre_install                                                          : reference/api/#pdm.signals.pre_install
    pdm.signals.pre_invoke                                                           : reference/api/#pdm.signals.pre_invoke
    pdm.signals.pre_lock                                                             : reference/api/#pdm.signals.pre_lock
    pdm.signals.pre_publish                                                          : reference/api/#pdm.signals.pre_publish
    pdm.signals.pre_run                                                              : reference/api/#pdm.signals.pre_run
    pdm.signals.pre_script                                                           : reference/api/#pdm.signals.pre_script
py:function
    pdm.core.Core.add_config                                                         : reference/api/#pdm.core.Core.add_config
    pdm.core.Core.create_project                                                     : reference/api/#pdm.core.Core.create_project
    pdm.core.Core.get_command                                                        : reference/api/#pdm.core.Core.get_command
    pdm.core.Core.handle                                                             : reference/api/#pdm.core.Core.handle
    pdm.core.Core.load_plugins                                                       : reference/api/#pdm.core.Core.load_plugins
    pdm.core.Core.main                                                               : reference/api/#pdm.core.Core.main
    pdm.core.Core.push_state                                                         : reference/api/#pdm.core.Core.push_state
    pdm.core.Core.register_command                                                   : reference/api/#pdm.core.Core.register_command
    pdm.project.core.Project.env_or_setting                                          : reference/api/#pdm.project.core.Project.env_or_setting
    pdm.project.core.Project.find_interpreters                                         : reference/api/#pdm.project.core.Project.find_interpreters
    pdm.project.core.Project.get_provider                                            : reference/api/#pdm.project.core.Project.get_provider
    pdm.project.core.Project.get_reporter                                            : reference/api/#pdm.project.core.Project.get_reporter
    pdm.project.core.Project.get_repository                                          : reference/api/#pdm.project.core.Project.get_repository
    pdm.project.core.Project.get_setting                                             : reference/api/#pdm.project.core.Project.get_setting
    pdm.project.core.Project.iter_interpreters                                         : reference/api/#pdm.project.core.Project.iter_interpreters
    pdm.project.core.Project.resolve_interpreter                                         : reference/api/#pdm.project.core.Project.resolve_interpreter
    pdm.project.core.Project.use_pyproject_dependencies                                         : reference/api/#pdm.project.core.Project.use_pyproject_dependencies
    pdm.project.core.Project.write_lockfile                                          : reference/api/#pdm.project.core.Project.write_lockfile
    pdm.pytest.PDMCallable.__call__                                                  : dev/fixtures/#pdm.pytest.PDMCallable.__call__
    pdm.pytest.RunResult.print                                                       : dev/fixtures/#pdm.pytest.RunResult.print
    pdm.pytest.build_env                                                             : dev/fixtures/#pdm.pytest.build_env
    pdm.pytest.build_env_wheels                                                      : dev/fixtures/#pdm.pytest.build_env_wheels
    pdm.pytest.local_finder_artifacts                                                : dev/fixtures/#pdm.pytest.local_finder_artifacts
    pdm.pytest.pdm                                                                   : dev/fixtures/#pdm.pytest.pdm
    pdm.pytest.project                                                               : dev/fixtures/#pdm.pytest.project
    pdm.pytest.project_no_init                                                       : dev/fixtures/#pdm.pytest.project_no_init
    pdm.pytest.pypi_indexes                                                          : dev/fixtures/#pdm.pytest.pypi_indexes
    pdm.pytest.remove_pep582_path_from_pythonpath                                         : dev/fixtures/#pdm.pytest.remove_pep582_path_from_pythonpath
    pdm.pytest.repository                                                            : dev/fixtures/#pdm.pytest.repository
    pdm.pytest.repository_pypi_json                                                  : dev/fixtures/#pdm.pytest.repository_pypi_json
    pdm.pytest.venv_backends                                                         : dev/fixtures/#pdm.pytest.venv_backends
    pdm.pytest.working_set                                                           : dev/fixtures/#pdm.pytest.working_set
py:module
    pdm.signals                                                                      : reference/api/#pdm.signals

I'm not familiar with MkDocs and how sources are defined to include/exclude code, but it appears several key libraries are not documented, e.g. all libraries in the resolver subpackage.

$ python -m sphinx.ext.intersphinx 'https://pdm.fming.dev/latest/objects.inv' | grep resolver
$

I assume that the current scope of API and Development guide documentation is limited to whatever is deemed relevant to PDM users, developers and/or contributors. But as a general comment, I feel it would be good idea to document all public (or at least, non-private) members across libraries and subpackages.