Christopher Arndt schrieb:
> Jorge Vargas schrieb:
>> On 1/20/07, Karl Guertin <[EMAIL PROTECTED]> wrote:
>>> I'm fine with creating docs directly under 1.0, I do that when I'm
>>> writing docs. I think only Adam and the people that came on during the
>>> sprint put docs in 1.0/RoughDocs. ;]
>>>
>> the only problem I see with that is that some docs that the creator
>> forgets to put into a link to it in RoughDocs may get *lost*
>
> Well, would be a good idea to make that point clear on the DocHelp page and
> also, that every document should have a ":Status: Draft|Official|Obsolete" tag
> at the top.
Here's an update to the DocHelp page as an attachment, since I can't edit the
original page and I can't save it as another page either, because of the acl
directive at the top. Could some editor check it out and update the page in the
wiki if appropriate, please?
BTW, I want to apply for editor rights on the wiki. Who do I have to bribe? ;-)
Chris
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"TurboGears Docs" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/turbogears-docs?hl=en
-~----------~----~----~----~------~----~------~--~---
##This is an official page. Only editors and admins can change it.
#acl All:read EditorGroup:read,write
#format rst
Contributing Docs to TurboGears
===============================
:status: Official
There are three ways to help make and maintain TurboGears documentation:
1. Comment! Pages should all have a comments box at the bottom. Add your
comments if you see a problem.
2. Add to the RoughDocs section for the version of TurboGears you're using.
Anyone can add and edit documentation there. Please do!
3. Become an editor! Knowledgeable TurboGears users with the interest and
aptitude can become editors. Editors are able to edit the "official" docs.
If you're looking to contribute docs in RoughDocs or as an editor, be sure to
read the following sections and the `documentation team page <DocTeam>`_.
Documentation Format
--------------------
All documentation should be in ReStructuredText format, not the standard wiki
markup. This is very important for ensuring the long term value of the docs we
write. We expect to move to Docudo at some point in the future, and the use of
ReStructuredText will allow us to do that without complex document conversions.
There are two templates that should be used to get you going with your
document. Both templates set the format to ReST and they also include the
proper code to include the page comment form.
OfficialTemplate
For official docs, this template ensures that only editors can edit.
TurboGearsTemplate
For any unofficial docs.
All documentation pages should display their editorial status right below the
main heading (like this page does). Use the `field lists syntax`_ for the
status tag::
This is the main heading
========================
:Status: Draft
Possible status tag values could be "Official", "Unofficial", "Draft",
"Experimental", "Outdated", "Obsolete" etc.
.. _field lists syntax:
http://docutils.sourceforge.net/docs/user/rst/quickref.html#field-lists
MoinMoin includes a `page with a ReStructuredText primer
<HelpOnParsers/ReStructuredText/RstPrimer>`_ and also includes information on
the `use of ReST in MoinMoin <HelpOnParsers/ReStructuredText>`_.
Putting Docs in the Right Places
--------------------------------
All docs about the TurboGears framework *must* have a version number at the
beginning of the page name, in sub wiki syntax. If you write a page about
Apache deployment for TurboGears 1.0, that page should be called
1.0/ApacheDeployment. The MoinMoin ReST parser doesn't automatically link
WikiWords, so you'll need to use the ReST link syntax::
`1.0/ApacheDeployment`_ creates a link with that pagename as the text.
`Apache deployment <1.0/ApacheDeployment>`_ creates a link with nicer
text.
New articles should be linked from the `RoughDocs <1.0/RoughDocs>`_ page for
the proper version as long as they haven't been checked and approved by the
editors and given an "official" status. This also ensures that new documents
don't get lost and others can benefit from them and/or contribute.
Multi-page documents should use the sub wiki format to reflect the pages, e.g.
1.0/20MinuteWiki/Page1.
Style Guidelines
----------------
In an effort to keep the documentation consistent online and useful offline,
please follow these conventions:
1. Titles are underlined only, the order is =, -, ~, ` (backtick)
2. Literals are any chunk of code (including variable names and parameters) and
anything you type directly into a terminal. Literals are surrounded by double
backticks. If you run across one of the few instances of the older convention
of surrounding literals with quotes, please drop the quotes and replace with
double backticks.
3. A full command line should go in a block literal so that they're easier to
notice. Instead of ``tg-admin info``, you'd write::
tg-admin info
4. The name for the example package (e.g. Wiki 20) is ``*packagename*`` and the
python name is ``*appname*`` (e.g. ``wiki_20``).
5. Try to keep lines wrapped at 80 characters
6. The preferred link syntax is the standard ReStructured Text callout style::
This is an `example link`_.
.. _example link: 1.0/ExampleLink
7. Try to use lists for lists and don't bold text or italicize or something.
This mostly comes up when dealing with lists of arguments and whatnot, check
the `Configuration <1.0/Configuration>`_ page for an example::
``arg1``
argument 1 explanation text
``arg2``
argument 2 explanation text
.. macro:: [[PageComment2(nosmiley=1, notify=1)]]
