|
Size: 4514
Comment:
|
← Revision 9 as of 2008-11-15 14:00:27 ⇥
Size: 3213
Comment: converted to 1.6 markup
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 26: | Line 26: |
| '''navigation links at the bottom too''' Users should have a navigation bar at the bottom. This should be quite easy to do in the HTML templates. '''write new Makefile, handle automatic version info and checkout''' We need a Makefile so that one just does {{{ cd Doc make html }}} to extract version info from the sources and build the documentation. |
|
| Line 42: | Line 29: |
'''discuss the default role''' The reST markup {{{`xyz`}}} currently means \var{xyz}. However, since this only produces italic output it may make more sense to just use {{{*xyz*}}} for that and use the {{{`xyz`}}} markup as a shortcut for something else, like a generic "object" cross reference. '''discuss lib -> ref section move''' I've moved the "Builtin objects/functions/exceptions" sections from the library reference to the language reference. It makes more sense to me, but remains to be discussed if it is generally a good thing. |
|
| Line 66: | Line 45: |
| == Conversion == When we find the toolset reasonably complete, we'll convert both the Python 2.6 and Python 3.0 SVN documentation branches to the new system. The conversion itself is (should be, you'll see yourself) painless, but it can't do everything right. For example, as the toplevel documents were completely separate until now, you couldn't directly link from, e.g. the library reference to a specific section of the language reference. These links will have to be corrected. All these tasks to do after conversion are listed in the ``doctools/converter/newfiles/TODO`` file, which is copied to the reST source tree on conversion. All other tasks that are independent of the converter are collected in ``doctools/TODO``. |
|
| Line 77: | Line 47: |
| Of course, before the conversion changes to existing documents have to be made in LaTeX to the original sources. However, you can already start extending and editing the "new" sources in `converter/newfiles` which don't have a LaTeX counterpart. | '''Roundup bugs''' |
| Line 79: | Line 49: |
| '''SF bugs''' | There are lots of bugs and feature requests in the Python issue tracker at http://bugs.python.org/, and even the occasional patch with category "Documentation". However, most of these are pretty big tasks though, such as (mostly obscure or advanced) features that are not documented, or documented not in the official docs, but some essay (new-style classes!). |
| Line 81: | Line 51: |
| There are lots of SF bugs and feature requests, and even the occasional patch with category "Documentation". However, most of these are pretty big tasks though, such as (mostly obscure or advanced) features that are not documented, or documented not in the official docs, but some essay (new-style classes!). | If you tackle an issue, mention the issue number in the commit message or in the patch email, and I will close the report accordingly. |
| Line 83: | Line 53: |
| The bug tracker is at http://sourceforge.net/tracker/?group_id=5470&atid=105470, the RFE and patches trackers can be reached through the "Tracker" menu at the page top. | '''In the Wiki''' There are also quite a few wiki pages concerning things missing from the documentation, see MissingFromDocumentation and CategoryDocumentation. '''Python 3000''' The Python 3.0 docs are still quite out of date; many PEPs and changes mentioned in "What's new in Python 3" or Misc/NEWS are not documented yet. I've read through the language reference and done some things myself, but only inserted XXX comments for others. Similarly, the library reference is the place where code samples must be read through and adapted to Python 3 syntax if applicable. |
Tasks
for the documentation team
Coding tasks
for those who want to develop the toolset
Get into the code
The first task for those who want to develop the toolset is to make themselves familiar with it. There are two documents, called doctools/README and doctools/HACKING, which give a short introduction how to use the command line tools and how the code is laid out. Feel free to amend!
Improvement suggestions
- I'd like to ask all of you to look at the new built documentation and collect thoughts about it -- not the content, but mainly the infrastructure such as navigational elements, accessibility etc.
Note that the web application does use JavaScript in some places, but only for better usability (hopefully). Users without JavaScript may not lose any functionality. (This should be confirmed every now and then.)
The TODO file
The doctools/TODO file lists some things that should be done. At the moment, these are:
discuss and debug comments system
- The comments system is quite new and untested. How it deals with inline comments is not ideal.
write a "printable" (PDF) builder (export to latex, most probably)
- Of course, printable output was trivial for LaTeX sources. The Docutils do have a latex writer (two in fact) -- if it is stable enough to be used, it has to be extended to support our extra node types. Else, some other conversion must be devised.
prepare for databases other than sqlite for comments
- Does sqlite scale well enough for our comments? Though I think so, we should be prepared to make it easy to substitute something like postgres.
look at the old tools/ scripts, what functionality should be rewritten
There were quite a few tools in Doc/tools/, e.g. looking which modules were documented. Some of this functionality is obsolete now, some of it may be useful.
Py-in-the-sky ideas
- add search via Xapian? optionally have a contents tree view in the sidebar (AJAX based)?
Content tasks
Roundup bugs
There are lots of bugs and feature requests in the Python issue tracker at http://bugs.python.org/, and even the occasional patch with category "Documentation". However, most of these are pretty big tasks though, such as (mostly obscure or advanced) features that are not documented, or documented not in the official docs, but some essay (new-style classes!). If you tackle an issue, mention the issue number in the commit message or in the patch email, and I will close the report accordingly.
In the Wiki
There are also quite a few wiki pages concerning things missing from the documentation, see MissingFromDocumentation and CategoryDocumentation.
Python 3000
- The Python 3.0 docs are still quite out of date; many PEPs and changes mentioned in "What's new in Python 3" or Misc/NEWS are not documented yet. I've read through the language
reference and done some things myself, but only inserted XXX comments for others.
- Similarly, the library reference is the place where code samples
must be read through and adapted to Python 3 syntax if applicable.