Project

Profile

Help

Issue #842

Installation docs are not easily linkable and numbering is messed up.

Added by bmbouter almost 7 years ago. Updated almost 3 years ago.

Status:
CLOSED - WONTFIX
Priority:
Normal
Assignee:
-
Category:
-
Sprint/Milestone:
-
Start date:
Due date:
Estimated time:
Severity:
1. Low
Version:
Platform Release:
OS:
Triaged:
Yes
Groomed:
No
Sprint Candidate:
No
Tags:
Documentation, Pulp 2
Sprint:
Quarter:

Description

The installation docs have two problems. (1) The numbering is messed up. It is constantly restarting at one. (2) The section is really long and isn't very linkable. This makes it hard to link someone to a specific section which I've wanted to do before.

Associated revisions

Revision c4d113c3 View on GitHub
Added by semyers about 6 years ago

docs no longer mention qpid-cpp-store

qpid-cpp-linearstore is available in all supported distributions now (woot), so we can remove the note about how you might want to install it instead of the -store package in favor of installing the -linearstore package everywhere.

There are also some minor docs fixes:

  • Indentations fixed so autonumbering works correctly in the 'Server' installation steps
  • Added subsections to the Repositories section of the install guide, and made the brokers subsection call out that the guide expects qpid to be installed

https://pulp.plan.io/issues/1341

fixes #1341

https://pulp.plan.io/issues/842

refs #842

History

#1 Updated by mhrivnak almost 7 years ago

  • Triaged changed from No to Yes

#2 Updated by semyers about 6 years ago

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

#3 Updated by bmbouter about 6 years ago

  • Subject changed from Installation docs numbering resets and is not linkable to Installation docs are not easily linkable
  • Description updated (diff)

I think we should leave it open. I've changed the title to clearly focus on the remaining part.

Also we already have intersphinx configured for linking between plugins and platform (hub-and-spoke style). You'll find the configs in our sphinx configurations. We use it some, but should probably use it more.

#4 Updated by semyers about 6 years ago

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.

#5 Updated by bmbouter about 6 years ago

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)".

#6 Updated by bmbouter about 6 years ago

  • Subject changed from Installation docs are not easily linkable to Installation docs are not easily linkable and numbering is messed up.
  • Description updated (diff)

#7 Updated by semyers about 6 years ago

I had it working in my local build :(

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

sphinx-voodoo--

#8 Updated by rbarlow about 6 years ago

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.

#9 Updated by bmbouter about 6 years ago

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

#10 Updated by jcline@redhat.com over 5 years ago

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

#11 Updated by bmbouter over 5 years ago

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

#12 Updated by bmbouter almost 3 years ago

  • Status changed from NEW to CLOSED - WONTFIX

#13 Updated by bmbouter almost 3 years ago

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.

#14 Updated by bmbouter almost 3 years ago

  • Tags Pulp 2 added

Also available in: Atom PDF