Project

Profile

Help

Task #2682

Add docs about how plugin writers can host their docs on docs.pulpproject.org

Added by amacdona@redhat.com over 2 years ago. Updated 6 months ago.

Status:
CLOSED - DUPLICATE
Priority:
Low
Assignee:
-
Category:
-
Sprint/Milestone:
Start date:
Due date:
% Done:

0%

Platform Release:
Blocks Release:
Backwards Incompatible:
No
Groomed:
Yes
Sprint Candidate:
No
Tags:
Documentation
QA Contact:
Complexity:
Smash Test:
Verified:
No
Verification Required:
No
Sprint:

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


Related issues

Duplicates Pulp - Task #2946: As a plugin writer, I know how to publish docs to RTD NEW Actions

History

#1 Updated by bmbouter over 2 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 amacdona@redhat.com over 2 years ago

  • Sprint Candidate changed from No to Yes

In our docs structure etherrpad we have the following sections for each plugin:

Installation
Quickstart
Workflows
API Reference
CLI Reference

http://pad-katello.rhcloud.com/p/pulp3_doc_structure

#3 Updated by amacdona@redhat.com over 2 years ago

  • Blocks Story #2859: As a developer, I have a template to create a new plugin added

#4 Updated by bizhang over 2 years ago

  • Tags Pulp 3 Plugin Writer Alpha added

#5 Updated by bmbouter over 2 years ago

  • 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)

#6 Updated by bmbouter over 2 years ago

  • Description updated (diff)

#7 Updated by ttereshc over 2 years ago

  • Description updated (diff)

#8 Updated by ttereshc over 2 years ago

  • Groomed changed from No to Yes

#9 Updated by mhrivnak over 2 years ago

  • Priority changed from Normal to Low

#10 Updated by mhrivnak over 2 years ago

  • Sprint/Milestone set to 42

#11 Updated by bmbouter about 2 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.

#12 Updated by bmbouter about 2 years ago

  • 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.

#13 Updated by ttereshc about 2 years ago

  • Blocks deleted (Story #2859: As a developer, I have a template to create a new plugin)

#14 Updated by ttereshc about 2 years ago

  • Blocked by Task #2946: As a plugin writer, I know how to publish docs to RTD added

#15 Updated by rchan over 1 year ago

  • Sprint Candidate deleted (Yes)

#16 Updated by amacdona@redhat.com 11 months ago

  • Sprint Candidate set to No
  • Tags Documentation added

#17 Updated by amacdona@redhat.com 6 months ago

  • Blocked by deleted (Task #2946: As a plugin writer, I know how to publish docs to RTD)

#18 Updated by amacdona@redhat.com 6 months ago

  • Blocks Release 2.19.z added

#19 Updated by amacdona@redhat.com 6 months ago

  • Duplicates Task #2946: As a plugin writer, I know how to publish docs to RTD added

#20 Updated by amacdona@redhat.com 6 months ago

  • Status changed from NEW to CLOSED - DUPLICATE
  • Blocks Release deleted (2.19.z)

#21 Updated by daviddavis 6 months ago

  • Sprint/Milestone set to 3.0

#22 Updated by bmbouter 6 months ago

  • Tags deleted (Pulp 3)

Please register to edit this issue

Also available in: Atom PDF