964540 - makedocs.pl should remove docs/en/doctrees after reST build is complete

Status: RESOLVED FIXED

(Bugzilla :: Documentation, defect)

Description

[David Lawrence [:dkl]]

SSIA

Comment 1

[Gervase Markham [:gerv]]

dkl: why? :-) I thought they are a cache which speeds up rebuilds?

It's true that removing an rst file from the rst/ dir requires blowing away the doctree/ dir (although I'd argue that's a bug in sphinx). Is that why?

Gerv

Comment 2

[Frédéric Buclin]

(In reply to Gervase Markham [:gerv] from comment #1)
> dkl: why? :-) I thought they are a cache which speeds up rebuilds?

The win is negligible as you don't recompile very often.


> It's true that removing an rst file from the rst/ dir requires blowing away
> the doctree/ dir (although I'd argue that's a bug in sphinx). Is that why?

That's one reason, but also because doctree/ is left in the tarballs otherwise.

Comment 3

[Gervase Markham [:gerv]]

Attachment: Patch v.1

Fair enough :-)

Gerv

Comment 4

[David Lawrence [:dkl]]

I also noticed when doing the release yesterday that the generated pdf is being placed in docs/en/latex/ instead of docs/en/pdf as before. Is this intentional? If not should just be a matter of updating the Makefile.

dkl

Comment 5

[Gervase Markham [:gerv]]

(In reply to David Lawrence [:dkl] from comment #4)
> I also noticed when doing the release yesterday that the generated pdf is
> being placed in docs/en/latex/ instead of docs/en/pdf as before. Is this
> intentional? If not should just be a matter of updating the Makefile.

That's where Sphinx puts it by default, because it goes via LaTeX to make the PDF. rst2pdf puts it in docs/en/pdf. 

I don't think having it in docs/en/latex/ breaks any links (because our website links to the version on RTD), and I can see it's simpler to have the two PDF output modes using different dirs. But if there's strong support for a change, it's an easy one.

Gerv

Comment 6

[David Lawrence [:dkl]]

(In reply to Gervase Markham [:gerv] from comment #5)
> I don't think having it in docs/en/latex/ breaks any links (because our
> website links to the version on RTD), and I can see it's simpler to have the
> two PDF output modes using different dirs. But if there's strong support for
> a change, it's an easy one.

Well for consistency and the fact when I see the directory as an admin, I don't automatically think a pdf file will be located in a directory called 'latex', we should probably put it in /pdf. Also since the script uses one method OR another and there really would never be 2 pdf files, they should both go to the same place IMO.

dkl

Comment 7

[Frédéric Buclin]

(In reply to David Lawrence [:dkl] from comment #6)
> Well for consistency and the fact when I see the directory as an admin, I
> don't automatically think a pdf file will be located in a directory called
> 'latex', we should probably put it in /pdf.

I agree; it should be in pdf/ in all cases.

Comment 8

[Frédéric Buclin]

Comment on attachment 8366579 [details] [diff] [review]
Patch v.1

r=LpSolit

Comment 9

[Gervase Markham [:gerv]]

Committing  to: bzr+ssh://bzr.mozilla.org/bugzilla/trunk/                      
modified docs/makedocs.pl
Committed revision 8913.

Gerv