The goal of this project is to create an unified and well-structured documentation for Pulp Project.
This document is organized as follows:
The goal of this project is to have an unified docs. But in order to aggregate from various sources and build something reasonable, we need some basic standarization.
Because of that, we've choose to addopt Diataxis as a basis for building such a standard. It defines a user-driven approach which outlines 4 content-types, which we'll use as our basic documentation content types.
Furthermore, we'll define personas, repository-types and a base folder structure, and how those structure can be translated in the presentation layer (the final website hierarchy, which doesn't have to be the same as the base folder-structure).
Here are the schematics of how these should work togheter:
graph
A["`
**persona** X **content-type**
`"]
B["`
**folder structure**
`"]
C["`
**presentation layer**
`"]
B -- strictly based on --> A
C -- flexibly based on --> A
C -- predictably fetches from --> B
We've identified three different user profiles for our product. These profiles will guide how we'll create and organize content.
For each persona, we'll use the 4 Diataxis categories:
Pulp Project has a complex set of plugins. We've categorized them to help organize content presentation.
In the project, we have the requirement of aggreating content from different repositories into a single build.
To make this work, each respository should know what content to create/update, so we've defined folder structure for each repository-type.
Note that this does not mean every one of these folder must be populated, it means they can. Later on we'll elaborate a priority plan of deliverables for orienting this.
CHANGES.md # expected to be here
staging_docs/
user/
tutorials/
guides/
learn/
reference/
admin/
tutorials/
guides/
learn/
reference/
dev/
tutorials/
guides/
learn/
reference/
[Changed in feb/24] Remove the global "reference" and use it as the other contents.
CHANGELOG.md
staging_docs/
(...) # same as other +
index.md # landing page
sections/
user/index.md
admin/index.md
dev/index.md
help/index.md
There are many ways in which these "Content-types x Personas" matrix can be arranged into a concrete documentation website (see complex hierarchies).
The first Live Demo was this. The actual one being used is this.
The current demo structure can be summarized in plain text as below. Other ideas on organizing the content in a hierarchy are very welcomed.
Home
User Manual
Overview
Pulpcore
Overview # optional
${tutorials,guides,learn,reference}
Plugins
${plugin-repo}
Overview # optional
${tutorials,guides,learn,reference}
Extra
${extra-repo}
Overview # optional
${tutorials,guides,learn,reference}
Admin Manual
(...) # same as previous
Developer Manual
(...) # same as previous
Help
Get Involved
PulpCon
Documentation Usage/
Changelogs/
Governance/
The following choices were based primarily in popularity/maintanability:
For the aggregation, we starrted with mkdocs-multirepo-plugin, but after some experimentation it proved itself not enough flexible to get content from the proposed content type structure to the presentation layer structure.
Because of that, we've developed pulp-docs, a python package to help build and serve the docs. It uses a mkdocs-macros-plugin hook to inject a preparation script into the mkdocs processing workflow. Additionally, it should help develop and distribute future doc tooling and automations across all repos, such as configured linting and other kind of automations, while also making it easier to run the docs locally regardless of a full oci-env setup.
The publishing workflow is define in pulpcore and should be configured to run nightly and publish to https://staging-docs.pulpproject.org/.
Here's a recommended workflow:
tmp_docstmp_docs to markdown all at once using rst2mysttmp_docs to version control so you can work on it over timetmp_docs to staging_docstmp_docs is empty, the work is done and it can be removedHere's some helpful commands to setup the repository:
#!/bin/bash
# 1. create structure
mkdir -p staging_docs/{admin,user,dev}/{guides,tutorials,learn,reference}
touch staging_docs/{admin,user,dev}/{guides,tutorials,learn,reference}/.gitkeep
cp -r docs tmp_docs
# 2. convert to rst->markdown (optional)
pip install rst-to-myst[sphinx]
find tmp_docs -name '*.rst' -exec rst2myst convert --replace-files {} ';'
# 3. extra automated cleaning
DOCDIR=tmp_docs
find $DOCDIR -type f -name "*.md" -exec sed -i -e 's/:::{note}/!!! note/' {} ';'
find $DOCDIR -type f -name "*.md" -exec sed -i -e 's/:::{tip}/!!! tip/' {} ';'
find $DOCDIR -type f -name "*.md" -exec sed -i -e 's/:::{warning}/!!! warning/' {} ';'
find $DOCDIR -type f -name "*.md" -exec sed -i -e 's/:::{hint}/!!! tip/' {} ';'
find $DOCDIR -type f -name "*.md" -exec sed -i -e 's/:::{glossary}//' {} ';'
find $DOCDIR -type f -name "*.md" -exec sed -i -e 's/{term}//' {} ';'
find $DOCDIR -type f -name "*.md" -exec sed -i -e 's/{github}//' {} ';'
find $DOCDIR -type f -name "*.md" -exec sed -i -e 's/{ref}//' {} ';'
find $DOCDIR -type f -name "*.md" -exec sed -i -re 's/^\([a-zA-Z-]+\)=$//' {} ';' # remove (something)=
find $DOCDIR -type f -name "*.md" -exec sed -i -re 's/`([a-zA-Z ]*)<\w*>`/`\1`/' {} ';' # remove `some thing <RemoveThis>`
find $DOCDIR -type f -name "*.md" -exec sed -i -e 's/:::$//' {} ';'
(Taken from this gist)
The motivation for having tmp_dir is to make it easier to determine what files were already migrated and what remains. If there is not much content in the repo, that may not be necessary.
Some guidance on how to choose the right place to put some content.
Mkdocs provides a superset of features over markdown.
Here we'll mention only fundamental decisions that should be followed. For more extensive reference on other markdown "components", see the live cheatsheet.
this is a [link](site:{repo}/docs/{persona}/{content-type}/page.md).
We won't support file includes for now. Move their content to markdown files.
!!note or !!warning et al
{persona}/index.md (e.g. user/index.md)admin/guidesadmin/reference (its extensive and descriptive material){persona}/reference (for the persona it makes more sense)user/reference
Q1 Increase the adoption of Pulp upstream by improving the documentation for new and existing users.
Q2 - Proposal Increase the adoption of Pulp upstream by improving the documentation for new and existing users.
-
Any changes
Be notified of any changes
-
Mention me
Be notified of mention me
-
Unsubscribe
Subscribe