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

Directory of an EUPS package.

skipped_names

List of package or module names to skip when creating links.

Returns
doc_dirs

Metadata about a stack package’s documentation content.

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

Return type

Package