Add docs about how plugin writers can host their docs on docs.pulpproject.org
This should be roughly a two paragraph task which will add a section on Docs to the plugin writer's guide.
Explain that plugin writers can host their docs however they want, but some popular options are hosting on docs.pulpproject.org, readthedocs.org, on github pages, or via readme files in the plugin's repo on github.
Explain that to host on docs.pulpproject.org your docs must meet the minimum requirements which is that your docs can be built by Sphinx with
git clone <your repo>;cd <your repo>/docs; make clean; make html. The plugin template should already provide this.
To enroll a plugin's docs on docs.pulpproject.org send an email request to the pulp-dev mailing list with the repo details.
Here is the suggested structure for all the docs, put the content described above into the Documentation section under Plugins: http://pad-katello.rhcloud.com/p/pulp3_doc_structure
#1 Updated by bmbouter over 3 years ago
Let me recap what we do with Pulp2 and docs. We host them all at docs.pulpproject.org and they get built and pushed there from Jenkins. It holds lots of versions (including our 3.0 nightlies) http://pulpproject.org/docs/ The plugin docs are each kept in a docs folder in the repo so that they can be built and submitted with plugin changes. All plugin docs are brought in through the Jenkins builder so they get served from docs.pulpproject.org.
In terms of what content should go in each, they usually contain a user guide, installation, quickstart, recipes, CLI. Would the guidelines be for just plugins maintained by the core devs (rpm, python, puppet, etc) or is it also for community plugins? I think if we focus on having our plugin docs be great, community plugin writers can mimic them or make their own choices. Getting the basic structure right would be the start of great plugin docs. We could probably make a basic structure in pulp_rpm on 3.0-dev and then replicate that to avoid having to formally document this.
#2 Updated by email@example.com over 3 years ago
- Sprint Candidate changed from No to Yes
In our docs structure etherrpad we have the following sections for each plugin:
#11 Updated by bmbouter about 3 years ago
I don't think we have a plan currently about hosting plugin docs. We probably cannot continue with what we did in Pulp2 for a variety of reasons:
- We can't have an error in 1 plugin stop docs building in core or other plugins
- "The Versions Problem": plugins are versioned differently from each other and core, hosting all of these versions on one site that is versioned by core doesn't make sense.
- Having one epic docs builder doesn't allow plugin writers to submit their work as PRs because it's too complicated. It's too complicated due to it having to handle docs production for core and all plugins across multiple versions and release types.
Please register to edit this issue