Project

Profile

Help

Task #2946

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

Added by ttereshc about 2 years ago. Updated 30 days ago.

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

0%

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

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

Duplicated by Pulp - Task #2682: Add docs about how plugin writers can host their docs on docs.pulpproject.org CLOSED - DUPLICATE Actions

History

#1 Updated by ttereshc about 2 years ago

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

#2 Updated by ttereshc about 2 years ago

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

#3 Updated by ttereshc about 2 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)

#4 Updated by bmbouter about 2 years ago

  • Groomed changed from No to Yes

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

#5 Updated by amacdona@redhat.com 6 months 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
  • 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.

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

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

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

  • Duplicated by Task #2682: Add docs about how plugin writers can host their docs on docs.pulpproject.org added

#8 Updated by bmbouter 6 months ago

  • Tags deleted (Pulp 3)

#9 Updated by CodeHeeler 5 months ago

  • Sprint set to Sprint 53

#10 Updated by amacdona@redhat.com 5 months ago

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

#11 Updated by CodeHeeler 5 months ago

  • Tags Plugin Template added

#12 Updated by amacdona@redhat.com 5 months ago

  • Sprint changed from Sprint 53 to Sprint 54

#13 Updated by ttereshc 4 months ago

  • Sprint changed from Sprint 54 to Sprint 55

#14 Updated by dkliban@redhat.com 3 months ago

  • Sprint changed from Sprint 55 to Sprint 56

#15 Updated by rchan 3 months ago

  • Sprint changed from Sprint 56 to Sprint 57

#16 Updated by rchan about 2 months ago

  • Sprint changed from Sprint 57 to Sprint 58

#17 Updated by rchan about 1 month ago

  • Sprint changed from Sprint 58 to Sprint 59

#18 Updated by bmbouter about 1 month ago

  • Sprint/Milestone deleted (3.0)

#19 Updated by amacdona@redhat.com 30 days ago

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

Please register to edit this issue

Also available in: Atom PDF