Project

Profile

Help

Task #2946

closed

As a plugin writer, I know how to publish docs to RTD

Added by ttereshc over 6 years ago. Updated over 3 years ago.

Status:
CLOSED - WONTFIX
Priority:
Normal
Assignee:
-
Category:
-
Sprint/Milestone:
-
Start date:
Due date:
% Done:

0%

Estimated time:
Platform Release:
Groomed:
Yes
Sprint Candidate:
No
Tags:
Documentation, Plugin Template
Sprint:
Quarter:

Description

Here are some points to take into account:

  • we want plugin docs to be built independently from the core ones
  • not to be blocked from building docs due to error in plugin docs (this is especially relevant to the community plugins where we potentially can do nothing to fix the docs)
  • plugin docs version can't be defined by core, plugins depend more on a plugin API version than on the core one.
  • unified search (across core and all the plugins) would be nice, if possible
  • but it's likely that every plugin will have its own site for docs

Here is also a relevant IRC discussion:

[17:17:21] <bmbouter> we need to have each docs be it's own JJB job, not one epic docs builder
[17:17:52] <bmbouter> also we can't have our docs blocked from building due to an error in plugin docs, so we need some kind of two-stage build or something
[17:18:10] <bizhang> bmbouter, I think the reason it's one epic builder is so search works across all docs
[17:19:14] <bmbouter> originally it was because we had 6 RTD sites to maintain
[17:19:42] <bmbouter> unified search is also nice
[17:20:41] <asmacdo> unifiedsearch++
[17:20:50] <bmbouter> I'm conflicted on it because hosting lots of docs is nice but also hard
[17:21:32] <asmacdo> We could revisit the idea of a docs repository
[17:21:56] <asmacdo> it would split the PRs, but that doesn't seem like that big of a deal to me
[17:22:19] <bmbouter> s/ideas/problems/
[17:25:29] <bmbouter> asmacdo: the issue with one repo is that it doesn't allow for docs hosting as versioned by plugins
[17:26:07] <asmacdo> That's a deal breaker for me... 
[17:26:08] <bmbouter> which when you think about it, the way we would host "plugin docs" won't work even because it assumes the plugin's docs are appropriate as versioned by core
[17:26:27] <bmbouter> yeah it keeps bringing me back to, plugin writers should just use RTD
[17:27:14] <asmacdo> perhaps we could host them, but as separate projects
[17:28:02] <bmbouter> yes perhaps
[17:28:05] <asmacdo> python.pulpproject.org
[17:28:26] <ttereshc> if we have some unified automatic way to add plugins to our docs, we can try to build docs and include them only if there were no errors during build process
[17:28:31] <bmbouter> we could also just point a DNS name like that at RTD
[17:28:53] <bmbouter> ttereshc: yes but we still have "the versions problem"
[17:29:29] <bmbouter> as in the python plugin is at 1.8.3 (as an example), yet it's being browsed at http://docs.pulpproject.org/en/2.13/
[17:29:49] <ttereshc> :(
[17:31:01] <asmacdo> such an ugly problem
[17:32:28] <asmacdo> I think the uglier solution is that our core docs should be very very light
[17:34:11] <asmacdo> And each plugin can link to core docs for concepts, installation, etc but each plugin will need fairly comprehensive docs
[17:35:03] <bmbouter> I think having each plugin have its own site for docs is inevitable
[17:35:38] <bmbouter> and the uniformity of the pulp2 plugin docs made sense since they were uniformly produced, but with pulp3 that won't be the case, each plugin will likely release separately
[17:35:52] <bmbouter> thanks to the plugin api

Related issues

Has duplicate Pulp - Task #2682: Add docs about how plugin writers can host their docs on docs.pulpproject.orgCLOSED - DUPLICATE

Actions
Actions #1

Updated by ttereshc over 6 years ago

  • Blocks Task #2682: Add docs about how plugin writers can host their docs on docs.pulpproject.org added
Actions #2

Updated by ttereshc over 6 years ago

  • Subject changed from Build docs for core and each plugin independently to Plan how to build and host docs for plugins
Actions #3

Updated by ttereshc over 6 years ago

  • Subject changed from Plan how to build and host docs for plugins to Plan how to host docs for community plugins
  • Description updated (diff)
Actions #4

Updated by bmbouter over 6 years ago

  • Groomed changed from No to Yes

This looks clear enough to groom. Thanks ttereshc for writing!

Actions #5

Updated by amacdona@redhat.com almost 5 years ago

  • Project changed from Packaging to Pulp
  • Subject changed from Plan how to host docs for community plugins to As a plugin writer, I know how to publish docs to RTD
  • Sprint/Milestone set to 3.0.0
  • Sprint Candidate changed from No to Yes

Currently, the plan is for each plugin to host on their own. These docs should provide links and minimal explanation for hosting plugin docs on rtd.

Actions #6

Updated by amacdona@redhat.com almost 5 years ago

  • Blocks deleted (Task #2682: Add docs about how plugin writers can host their docs on docs.pulpproject.org)
Actions #7

Updated by amacdona@redhat.com almost 5 years ago

  • Has duplicate Task #2682: Add docs about how plugin writers can host their docs on docs.pulpproject.org added
Actions #8

Updated by bmbouter almost 5 years ago

  • Tags deleted (Pulp 3)
Actions #9

Updated by CodeHeeler almost 5 years ago

  • Sprint set to Sprint 53
Actions #10

Updated by amacdona@redhat.com almost 5 years ago

  • Status changed from NEW to ASSIGNED
  • Assignee set to amacdona@redhat.com
Actions #11

Updated by CodeHeeler almost 5 years ago

  • Tags Plugin Template added
Actions #12

Updated by amacdona@redhat.com almost 5 years ago

  • Sprint changed from Sprint 53 to Sprint 54
Actions #13

Updated by ttereshc over 4 years ago

  • Sprint changed from Sprint 54 to Sprint 55
Actions #14

Updated by dkliban@redhat.com over 4 years ago

  • Sprint changed from Sprint 55 to Sprint 56
Actions #15

Updated by rchan over 4 years ago

  • Sprint changed from Sprint 56 to Sprint 57
Actions #16

Updated by rchan over 4 years ago

  • Sprint changed from Sprint 57 to Sprint 58
Actions #17

Updated by rchan over 4 years ago

  • Sprint changed from Sprint 58 to Sprint 59
Actions #18

Updated by bmbouter over 4 years ago

  • Sprint/Milestone deleted (3.0.0)
Actions #19

Updated by amacdona@redhat.com over 4 years ago

  • Status changed from ASSIGNED to NEW
  • Assignee deleted (amacdona@redhat.com)
  • Sprint deleted (Sprint 59)
Actions #20

Updated by rchan about 4 years ago

  • Sprint Candidate deleted (Yes)
Actions #21

Updated by daviddavis over 3 years ago

  • Status changed from NEW to CLOSED - WONTFIX
  • Sprint Candidate set to No

Also available in: Atom PDF