Pulp

This is two separate issues. The first issue is easy to fix (and also demonstrate as being fixed)

Making the installation section easily linkable is a case of "you don't know what you don't know". I don't know if we can do much to reduce the length of the server installation sections, but linking to it should be doable as-needed with sphinx cross references:

http://sphinx-doc.org/markup/inline.html#cross-referencing-arbitrary-locations

I sorta accedentally fixed the first part in an unrelated PR[0] because I just assumed the breakage was my fault, so if we want to sorta ignore part 2 of the OP, then this can go POSTal.

[0]: https://github.com/pulp/pulp/pull/2228

I think intersphinx is orthogonally related the issue I mentioned, though: without knowing what sections we want to link to, we can't make it any easier to link to those sections. I'm not sure how we can ever close this without adding specifics.

Arbitrary location refs potentially solve the issue for both local sphinx and intersphinx builds, so I'm still leaning the other way. I think that this issue ought to be closed and any specific linking issues outstanding should be opened as their own issues.

I just compiled the merged changes from 2228, and it looks like the numbering is still a problem. In the server section I get 1, 2, 3, 4, 5, 1, 2, 3 all in the same section.

Also regarding how to make the section linkable, specifically the numbers of the Server section should be able to be linked to. This could be that we just need to add link targets (after the numbering is fixed). Or the 1, 2, 3, 4, 5, 1, 2, 3 could be sliced up into 3 subsections with numbers per section. This would also make it more linkable.

The use case is, I want to link users to the docs and say "look more closely in this part (ie: # 4)".

I had it working in my local build :(

It's better than it was, though barely...

sphinx-voodoo--

FWIW, one thing that I think makes some of our competitors easier to use is that they have a single documentation project where all their type support is together, as opposed to our highly fragmented documentation. The way our docs are now are more convenient for us developers because we can create a feature and docs together in a single pull request, but in my opinion this is at the expense of our users as the documentation is difficult to navigate and even difficult to know about as it is. I was helping a user on Freenode late at night on Thursday and they had a difficult time even finding our rpm documentation.

I think we should seriously consider just making the docs have their own repository and unifying the platform and all plugins into a single Sphinx project.

rbarlow wrote:

FWIW, one thing that I think makes some of our competitors easier to use is that they have a single documentation project where all their type support is together, as opposed to our highly fragmented documentation. The way our docs are now are more convenient for us developers because we can create a feature and docs together in a single pull request, but in my opinion this is at the expense of our users as the documentation is difficult to navigate and even difficult to know about as it is. I was helping a user on Freenode late at night on Thursday and they had a difficult time even finding our rpm documentation.

I think we should seriously consider just making the docs have their own repository and unifying the platform and all plugins into a single Sphinx project.

+1000

Do you still feel this way after your consolidation of the docs, or can we close this issue?

The numbering is still wrong so I think we should leave this open until that is resolved.

Pulp 2 is approaching maintenance mode, and this Pulp 2 ticket is not being actively worked on. As such, it is being closed as WONTFIX. Pulp 2 is still accepting contributions though, so if you want to contribute a fix for this ticket, please reopen or comment on it. If you don't have permissions to reopen this ticket, or you want to discuss an issue, please reach out via the developer mailing list.