Opened 8 years ago

Closed 3 years ago

#3409 enhancement closed wontfix (wontfix)

doc/ directory should contain a brief explanation of how to generate the documentation from it

Reported by: Glyph Owned by:
Priority: normal Milestone:
Component: lore Keywords: documentation EndOfLore
Cc: Thijs Triemstra Branch: branches/lore-readme-3409
branch-diff, diff-cov, branch-cov, buildbot
Author: thijs

Description

If someone came along and wanted to help maintain the twisted documentation (wouldn't that be great?), they would probably not be able to guess the options to lore which would allow them to produce HTML or PDF documentation like the versions that we have on the website and proofread their markup.

There should be a README.txt that explains "run lore like this, in this directory".

I am assigning this to radix to make sure that this document is at least vaguely congruent, in any relevant way, with the way the documentation is generated for release.

Change History (10)

comment:1 Changed 8 years ago by Thijs Triemstra

Cc: Thijs Triemstra added
Keywords: documentation added
Owner: changed from radix to Thijs Triemstra
Status: newassigned

Yes, that would be useful indeed! Will ask someone on IRC about it.

comment:2 Changed 8 years ago by Glyph

Eventually I'd like to adjust the documented solution here to be 'cd doc; lore'.

For an example of how this might be set up, see http://divmod.org/trac/browser/trunk/Mantissa/doc/README.txt

comment:3 Changed 8 years ago by Thijs Triemstra

Author: thijs
Branch: branches/lore-readme-3409

(In [26446]) Branching to 'lore-readme-3409'

comment:4 Changed 8 years ago by Thijs Triemstra

Keywords: review added
Owner: Thijs Triemstra deleted
Status: assignednew

I added such a README file in doc/core/howto in r26449. Running 'lore' from the top folder (doc/) doesn't work (it returns getProcessor() failed).

comment:5 Changed 8 years ago by Glyph

Keywords: review removed
Owner: set to Thijs Triemstra

The toplevel doc/ directory needs a README as well, if it is expected that anyone will actually find this file.

Perhaps for the time being it should simply refer to doc/core/howto and there should be separate tickets for simplifying this process to work across all the projects? (Presumably also fixing the doc-building scripts, such as they are, to know about this?)

comment:6 Changed 7 years ago by Thijs Triemstra

Component: corelore

This is a lore-related ticket.

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

Owner: changed from Thijs Triemstra to khorn

comment:8 Changed 6 years ago by Glyph

Summary: doc/ directory should contain a brief explanation of how to run lore on itdoc/ directory should contain a brief explanation of how to generate the documentation from it

Updating description to be a little more future-proof.

comment:9 Changed 6 years ago by <automation>

Owner: khorn deleted

comment:10 Changed 3 years ago by khorn

Keywords: EndOfLore added
Resolution: wontfix
Status: newclosed

Lore is no longer being used for Twisted documentation, and is being deprecated, prior to eventual removal, per #6907.

This issue will not be fixed.

Note: See TracTickets for help on using tickets.