Pulp

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