Task #2682
closed
Add docs about how plugin writers can host their docs on docs.pulpproject.org
Status:
CLOSED - DUPLICATE
Description
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
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.
- Sprint Candidate changed from No to Yes
- Blocks Story #2859: As a developer, I have a template to create a new plugin added
- Tags Pulp 3 Plugin Writer Alpha added
- Subject changed from Planning: How will plugin documentation work? to Add docs about how plugin writers can host their docs on docs.pulpproject.org
- Description updated (diff)
- Description updated (diff)
- Description updated (diff)
- Groomed changed from No to Yes
- Priority changed from Normal to Low
- Sprint/Milestone set to 42
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.
- Sprint/Milestone deleted (
42)
- Tags deleted (
Pulp 3 Plugin Writer Alpha)
Per an IRC convo, since we don't have a plan for how to host docs currently, this is being removed from the alpha milestone and from the sprint.
- Blocks deleted (Story #2859: As a developer, I have a template to create a new plugin)
- Blocked by Task #2946: As a plugin writer, I know how to publish docs to RTD added
- Sprint Candidate deleted (
Yes)
- Sprint Candidate set to No
- Tags Documentation added
- Blocked by deleted (Task #2946: As a plugin writer, I know how to publish docs to RTD)
- Is duplicate of Task #2946: As a plugin writer, I know how to publish docs to RTD added
- Status changed from NEW to CLOSED - DUPLICATE
- Sprint/Milestone set to 3.0.0
Also available in: Atom
PDF
.