Opened 13 years ago

Closed 13 years ago

Last modified 3 years ago

#1515 defect closed fixed (fixed)

Web2 documentation should not disregard the Documentation Standard

Reported by: David Reid Owned by:
Priority: highest Milestone:
Component: web2 Keywords: documentation
Cc: jknight, hypatia, oubiwann Branch:
Author:

Description

Currently the web2 documentation uses it's ReST with it's own (undocumented) generation scripts, it should use lore just like all the other projects.

Change History (19)

comment:1 Changed 13 years ago by David Reid

Cc: jknight added; foom removed
Owner: changed from foom to David Reid

comment:2 Changed 13 years ago by edsuom

In the meantime, so the doc generation script actually works, you might add the following symlink:

doc/web2/generation-scripts/hier.py --> ../hier.py

SVN has no trouble maintaining symlinks anymore.

comment:3 Changed 13 years ago by jknight

Hm, thanks, I had a pyc leftover which is why I didn't notice that it was broken. Should be fixed now.

For the record, I disagree with the title of the bug.

comment:4 Changed 13 years ago by David Reid

Cc: hypatia added
Summary: Web2 documentation should use lore.Web2 documentation should not disregard the Documentation Standard

Clarification on the purpose of this bug. Currently Web2 is the odd man out by using ReST, even though we have some pretty good documentation there are some problems with it:

  1. It isn't generated with everyone elses.
  2. It violates the existing Documentation Standard.

The Summary has been changed to reflect the goal of "not disregard the documentation standard" as opposed to the goal of "use lore." I'm CCing hypatia so that we might get some outside input on some of the possible solutions:

  1. Extend the documentation standard
  2. Extend lore (and allow it to use multiple input formats for autogenerated documentation)
  3. Make web2 use lore

That being said, I prefer the 3rd solution as it is the most straightforward, can be done in an automatic way, and doesn't require a large consensus to be successful.

comment:5 Changed 13 years ago by jknight

I'll vote for:

  1. Keep using ReST as a source format and generate files suitable for input to lore from it.

For now. In my ideal world, all the twisted documentation would be magically converted away from Lore, but I'm not very optimistic about magic.

comment:6 Changed 13 years ago by David Reid

I don't believe #4 to be a valid option based on my natural tendancy to keep anything automatically generated out of version control, and the fact that people other than you or I might have reason to make changes to the documentation and the process shouldn't be any different than other Twisted documentation.

comment:7 Changed 13 years ago by jknight

Maybe I meant the same thing as what you meant by 2, then. I mean that the script for generating twisted documentation should invoke "convert ReST->Lore", then invoke lore on the output of that.

comment:8 Changed 13 years ago by David Reid

my #2 consists of the following steps

  1. write a ReST driver for lore
  2. change admin/process-docs to not require input in .xhtml
  3. change the documentation standard to allow subprojects to write documentation in any lore input format.

comment:9 Changed 13 years ago by Stephen Thorne

Discussing this issue with dreid I came up with this information:

16:54 < Jerub> dreid: how many lines of docs need to be convereted?
16:55 < _moshez> Jerub: I eat your tummy and poke it! also how are you
16:56 < dreid> Jerub: 651 according to wc -l ~/projects/Twisted/trunk/doc/web2/*.txt

On that basis, I see no reason not to use option number 3, "Make web2 use lore"

comment:10 Changed 13 years ago by oubiwann

Cc: oubiwann added

comment:11 Changed 13 years ago by Jean-Paul Calderone

The description of this ticket is correct.

All documentation for all Twisted projects should use lore. There should only be one source format for documentation: even though we could write a ReST input driver, doing so would defeat a large portion of the purpose of lore, which is to make it easy to write and maintain documentation (requiring everyone to learn lore xhtml and ReST is harder than requiring everyone to learn lore xhtml).

comment:12 Changed 13 years ago by jknight

Registering my disagreement of the above comment for posterity, just in case someone tries to tell me I didn't object. I think the docs should be kept in ReST format and lore (or whatever) taught to read them.

comment:13 Changed 13 years ago by David Reid

Status: newassigned

To clarify my intended approach to this bug I have started work on a rst input plugin for lore. I will be using this plugin to generate lore documentation from the current source, I will then tidy (by hand if necessary) the resulting document and checking that in to svn, so that it may be processed by admin/process-docs, while removing the rst documentation from version control.

branched to source:branches/web2-loredocs-1515

comment:14 Changed 13 years ago by David Reid

Keywords: review added
Owner: changed from David Reid to PenguinOfDoom
Status: assignednew

comment:15 Changed 13 years ago by Glyph

Priority: highhighest

Review tickets should be "highest" priority so they don't languish.

comment:16 Changed 13 years ago by PenguinOfDoom

Owner: changed from PenguinOfDoom to David Reid

Pilot, you are approved for merging. Transmitting ALS coordinates now.

comment:17 Changed 13 years ago by David Reid

Resolution: fixed
Status: newclosed

(In [17173]) Web2 Documentation is now written entirely in lore.

Author: dreid Reviewer: PenguinOfDoom Fixes #1515

comment:18 Changed 8 years ago by <automation>

Owner: David Reid deleted

comment:19 Changed 3 years ago by hawkowl

Cc: jknight, hypatia,oubiwannjknight, hypatia, oubiwann
Keywords: review removed

[mass edit] Removing review from closed tickets.

Note: See TracTickets for help on using tickets.