Platform vs. Type-Specific User Guides¶
The platform user guide should cover all generic features of Pulp. When examples are appropriate, it should use the “rpm” content type, but only utilize features that are generic across content types.
User guides for content types should avoid repeating what is already in the platform guide and instead focus on these two topics:
- What new features does this content type provide? For example, RPM support includes protected repos.
- Create a quick-start guide that shows examples of how to do the most basic and interesting operations. For example, create a repository, sync it, and publish it. Show more advanced stories as “recipes”.
Command Line User Guide¶
Our command line tools such as
pulp-consumer do a very
good job of self-documenting with help text. Pulp’s user guides should not
duplicate this information. Enumerating every flag and option of the CLI tools
would leave us with two places to maintain the same documentation, which would
inevitably go out of sync.
The user guides should instead add value beyond what the CLI tools can self-document. Focus on how to use specific features, show lots of examples, and keep in mind what use cases users are likely to be interested in.
Examples should not include long lines that will require horizontal scrolling.
All example commands should begin with only
$ as a prompt. Commands that
must be run as root should be shown using
Platform and plugins each have their own Sphinx project which allow docs to be
built without checking out additional repositories. The Sphinx project for
platform and each plugin are located in the
docs directory in the top level
of the repository. For example, the platform Sphinx project
is located here.
The current, stable GA release are hosted at https://docs.pulpproject.org/
GA releases for version X.Y are hosted at https://docs.pulpproject.org/en/X.Y/
A given X.Y version could have either a Beta or an RC but not both, so those are hosted at the same place https://docs.pulpproject.org/en/X.Y/testing/
Nightly docs for a given X.Y release are hosted at https://docs.pulpproject.org/en/X.Y/nightly/
Old doc versions not available on https://docs.pulpproject.org/ are available via source.
Editing the Docs¶
The Pulp docs support extlinks.
:redmine: directive to easily create links to Pulp issues. For
Creates a link to issue 123 like this: #123. You can also set the text for the link using this syntax:
:redmine:`my new link text <123>`
Which creates this link: my new link text There is also a
:fixedbugs_<project name>: directive to link to all bugs for a specific
version of Pulp or its plugins.
This is useful in release notes. For example:
Create a link to bugs fixed in Pulp 2.6.0 like this: bugs fixed in 2.6.0. This can have its link text set using the syntax:
:fixedbugs_pulp:`these great bugs were fixed <2.6.0>`
Which creates this link: these great bugs were fixed.
To create a link to bugs fixed in plugins, use their github project name in the directive.
For example, for RPM plugin, use the
Build Docs Locally¶
Building docs locally is easy:
- Navigate to the Sphinx project folder
- Browse the docs the folder
The Vagrant environment comes pre-loaded with all the dependencies you need to build the docs.
If the Python environment you build the docs in has the
Python package, the docs will have the same look and feel as
https://docs.pulpproject.org/. If not,
you will get the default Sphinx theme. Either should be sufficient for
proofing content changes.
You do not need to clean the docs before rebuilding. If you do need to
clean the docs, you should run
make clean from the documentation root.