[Docutils-develop] Re: Cleanup of doc directories

[Felix W. <Fel...@gm...>]

David Goodger wrote:

> [snip]

First of all, thank you for your detailed explanations.

> Perhaps we ought to think of this reorganized docs/ directory in terms
> of the different groups of Docutils stakeholders:
>
> 1. End-users: users of reStructuredText and the Docutils tools.  Many
>     are not developers.
>
> 2. Library-user/developers: developers using Docutils as a library,
>     programmers developing *with* Docutils.
>
> 3. Component-developers: those who implement application-specific
>     components, directives, and/or roles, without contributing them
>     back to Docutils.
>
> 4. Core-developers: developers of the Docutils codebase, participants
>     in the Docutils project community.
>
> 5. Alternate-implementers: developers of alternate implementations of
>     Docutils.

Maybe between 1 and 2:

Python-developers: developers utilizing reStructuredText or Docutils for
documentating their source.  All Python-developers are end-users, but
not vice versa.

> So the new directories to create are:
>
> * docs/user/: introductory/tutorial material for end-users
> * docs/dev/: for core-developers
> * docs/ref/: reference material for all groups
> * docs/howto/: for component-developers and core-developers
> * docs/lib/: API reference material for library-user/developers

Maybe also docs/python/ for Python-developers?

> I've updated the notes.txt file with my modifications to the plan.
> There are some questions there:
>
>    - PEPs in ``spec/``?  Move to ``docs/ref/`` or ``docs/dev/``?

PEP 258 to docs/lib/ (it's not a reference and it's not only relevant
for core-developers).  PEP 256, PEP 257, PEP 287 (and later Python
source reader documentation) to docs/python/, see above.

>    - Move ``alternatives.txt`` ... from ``spec/rst/`` to
>      ``docs/dev/rst/``.  (Move "Doctree Representation of Transitions"
>      section elsewhere?  Where?)

Am I right that it's actually only 'Internal Representation', 'Output'
and 'Implementation Plan' which have to be moved?

My ideas:

1. Leave it as is.  These three sections don't hurt.

2. Or create a new file (docs/dev/lineblocks.txt) and add a link in
   alternatives.txt.

3. Or move docs/dev/rst/alternatives.txt to docs/dev/alternatives.txt,
   so it isn't reST-specific.

>    - Move ... ``interpreted.txt`` from ``spec/rst/`` to
>    ``docs/ref/rst/``.  (Rename ``interpreted.txt`` to ``roles.txt``?)

I think 'roles.txt' is better.

-- 
When replying to my email address, ensure that the mail header contains
'Felix Wiemann'. Please don't send unrequested mails > 64 KB.

<http://www.ososo.de/>