find_package_docs

documenteer.stackdocs.pkgdiscovery.find_package_docs(package_dir, skipped_names=None)

Find documentation directories in a package using manifest.yaml and heuristics.

Parameters:

  • package_dir (Union[str, Path]) – Directory of an EUPS package.

  • skipped_names (Optional[List[str]], default: None) – List of package or module names to skip when creating links.

Returns:

Metadata about a stack package’s documentation content.

Return type:

doc_dirs

Raises:

NoPackageDocs – Raised when the manifest.yaml file cannot be found in a package.

Notes

Stack packages have documentation in subdirectories of their doc directory. The manifest.yaml file declares what these directories are so that they can be symlinked into the root project.

There are three types of documentation directories:

  1. Package doc directories contain documentation for the EUPS package aspect. This is optional.

  2. Module doc directories contain documentation for a Python package aspect. These are optional.

  3. Static doc directories are root directories inside the package’s doc/_static/ directory. These are optional.

These are declared in a package’s doc/manifest.yaml file. For example:

package: "afw"
modules:
  - "lsst.afw.image"
  - "lsst.afw.geom"
statics:
  - "_static/afw"

This YAML declares module documentation directories:

  • afw/doc/lsst.afw.image/

  • afw/doc/lsst.afw.geom/

It also declares a package documentation directory:

  • afw/doc/afw

And a static documentaton directory:

  • afw/doc/_static/afw