Opened 8 years ago

Closed 8 years ago

#6926 release blocker: regression closed fixed (fixed)

Make old "go to the current version of this document" from lore docs point at new sphinx docs

Reported by: Glyph Owned by: hawkowl
Priority: high Milestone: Twisted-14.0.0
Component: core Keywords: documentation
Cc: Branch: branches/fix-doc-locations-6926-2
branch-diff, diff-cov, branch-cov, buildbot
Author: hawkowl

Description

As noted on the original ticket, the current directory structure has been muddled around a bit, mostly by the addition of the somewhat spurious "projects" directory. We should rearrange the directory structure (and update the toctrees to reflect the re-organization) so that the URLs line up. As a bonus, the 'projects' tree is just unnecessarily deep nesting which probably doesn't provide any value anyway.

Change History (21)

comment:1 Changed 8 years ago by Glyph

Milestone: Twisted-14.0.0

comment:2 Changed 8 years ago by Glyph

Priority: normalhigh

We need to take care of this before release.

comment:3 Changed 8 years ago by hawkowl

Owner: set to hawkowl

I'll work on it tonight.

comment:4 Changed 8 years ago by hawkowl

Author: hawkowl
Branch: branches/fix-doc-locations-6926

(In [41966]) Branching to fix-doc-locations-6926.

comment:5 Changed 8 years ago by hawkowl

Keywords: review added

Okay, gave it a shot.

Please review.

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

Type: enhancementregression

comment:7 Changed 8 years ago by hawkowl

Owner: hawkowl deleted

comment:8 Changed 8 years ago by Jean-Paul Calderone

I forced a build of the branch. The documentation builder is green but unfortunately it still doesn't actually produce a working build of the documentation.

Apart from that, I wonder how to determine if this change addresses the issue or not? I suppose I should manually verify that the files generated by sphinx now have the same paths (and therefore will exist at the same URLs) as the files generated by lore before the conversion.

comment:9 Changed 8 years ago by Jean-Paul Calderone

Another issue here is how we will generate these links in the Sphinx documentation. Has that been implemented?

comment:10 Changed 8 years ago by hawkowl

I think the links aren't appearing because the doc builder has Sphinx 1.1, which doesn't support hidden toc trees or something.

Let's see if it works when I set 1.2 required, forced build...

comment:11 Changed 8 years ago by hawkowl

Yep, it fails. To build working docs, the buildslave needs Sphinx 1.2.

comment:13 Changed 8 years ago by hawkowl

Tom Prince merged and update the buildslaves, it now goes all green.

The buildslave also creates a working build for you now, exarkun :)

comment:14 Changed 8 years ago by Jean-Paul Calderone

Keywords: review removed
Owner: set to hawkowl

Another issue here is how we will generate these links in the Sphinx documentation. Has that been implemented?

comment:15 Changed 8 years ago by hawkowl

Keywords: review added
Owner: hawkowl deleted

This actually does it now! I used the same code as from lore's templates, put the link where I thought it'd be good.

comment:16 Changed 8 years ago by Jean-Paul Calderone

Why do both doc and docs still exist in this branch?

comment:17 Changed 8 years ago by Jean-Paul Calderone

Keywords: review removed
Owner: set to hawkowl

comment:18 Changed 8 years ago by hawkowl

Keywords: review added
Owner: hawkowl deleted

Nuked the doc/ directory - (for future reference: git doesn't track empty dirs, and didn't delete them when #4500 deleted all the files).

comment:19 Changed 8 years ago by Alex Gaynor

Keywords: review removed
Owner: set to hawkowl

This looks good to me.

comment:20 Changed 8 years ago by hawkowl

Branch: branches/fix-doc-locations-6926branches/fix-doc-locations-6926-2

(In [42139]) Branching to fix-doc-locations-6926-2.

comment:21 Changed 8 years ago by hawkowl

Resolution: fixed
Status: newclosed

(In [42144]) Merge fix-doc-locations-6926-2

Author: hawkowl Reviewers: exarkun, Alex Fixes: #6926

Fix the doc locations and add "go to current version of this document" to Sphinx built docs.

Note: See TracTickets for help on using tickets.