Opened 6 years ago

Closed 11 months 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 Branch: branches/lore-readme-3409
(diff, github, buildbot, log)
Author: thijs Launchpad Bug:

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 6 years ago by thijs

  • Cc thijs added
  • Keywords documentation added
  • Owner changed from radix to thijs
  • Status changed from new to assigned

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

comment:2 Changed 6 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 6 years ago by thijs

  • Author set to thijs
  • Branch set to branches/lore-readme-3409

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

comment:4 Changed 6 years ago by thijs

  • Keywords review added
  • Owner thijs deleted
  • Status changed from assigned to new

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 6 years ago by glyph

  • Keywords review removed
  • Owner set to thijs

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 5 years ago by thijs

  • Component changed from core to lore

This is a lore-related ticket.

comment:7 Changed 4 years ago by exarkun

  • Owner changed from thijs to khorn

comment:8 Changed 4 years ago by glyph

  • Summary changed from doc/ directory should contain a brief explanation of how to run lore on it to doc/ 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 4 years ago by <automation>

  • Owner khorn deleted

comment:10 Changed 11 months ago by khorn

  • Keywords EndOfLore added
  • Resolution set to wontfix
  • Status changed from new to closed

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.