Opened 6 years ago

Closed 6 years ago

#5419 enhancement closed duplicate (duplicate)

there should be an index which links to all twisted documentation

Reported by: ivank Owned by:
Priority: normal Milestone:
Component: core Keywords: documentation easy
Cc: ivank Branch:
Author:

Description

For a while I assumed there was no twisted.web documentation, because it wasn't listed in /core/howto/index.html. Today I landed /core/howto/index.html via Google and failed to find twisted.names documentation. "Oh, I have to edit core -> names in the URL."

My proposal is to link to all of the non-core documentation on this page.

Change History (4)

comment:1 Changed 6 years ago by ivank

exarkun tells me that [1] links to everything anyway, but [2] still has the same problem: a page titled "Twisted Documentation" doesn't list all of the documentation (and this is the page that Google will probably like the most).

[1] http://buildbot.twistedmatrix.com/builds/sphinx-html/518-16067/

[2] http://buildbot.twistedmatrix.com/builds/sphinx-html/518-16067/projects/core/howto/index.html

comment:2 Changed 6 years ago by Glyph

Summary: /core/howto/index.html should link to non-core documentationthere should be an index which links to all twisted documentation

The core documentation is for the core. It shouldn't link all over the place just because people look at it sometimes.

The real URL with a problem is http://twistedmatrix.com/documents/current/ - this is arguably the most important page in the Twisted documentation, and it obviously isn't a very good guide. The sphinx page you cite is basically a replacement for that link, and it's a lot better (notice that there's navigation across the top).

I've updated the summary.

comment:3 in reply to:  2 Changed 6 years ago by msabramo

Replying to glyph:

The real URL with a problem is http://twistedmatrix.com/documents/current/ - this is arguably the most important page in the Twisted documentation, and it obviously isn't a very good guide. The sphinx page you cite is basically a replacement for that link, and it's a lot better (notice that there's navigation across the top).

If I wanted to tackle this, should I just change links that I find to point to the buildbot-generated Sphinx pages instead of the static versions? And remove the old static HTML versions?

Or does the Sphinx output need to be copied to a more stable place?

comment:4 Changed 6 years ago by Jean-Paul Calderone

Resolution: duplicate
Status: newclosed

Notice that http://twistedmatrix.com/documents/current/ is actually a complete index now. It was not when glyph wrote his comment. It could still be better, but I think it's actually good enough to resolve this ticket. The change was done for #5429, which was effectively a duplicate of this ticket.

We should not start dropping links to random Sphinx builds of the documentation all over the place. Those are for the development version of Twisted, there is no guarantee they'll stick around (there is a guarantee they won't, actually), and the Sphinx conversion isn't complete yet.

Note: See TracTickets for help on using tickets.