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

[glyph]

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.

[thijs]

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

[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

[thijs]

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

[thijs]

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).

[glyph]

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?)

[thijs]

This is a lore-related ticket.

[glyph]

Updating description to be a little more future-proof.