Warning: Can't synchronize with repository "(default)" (Unsupported version control system "svn": No module named svn). Look in the Trac log for more information.

Ticket #1646 (closed defect: duplicate)

Opened 10 years ago

Last modified 7 years ago

Documentation Strategy

Reported by: lszyba1 Owned by: Chris Arndt
Priority: high Milestone: 1.5
Component: Documentation Version: 1.0.4b3
Severity: critical Keywords:
Cc:

Description

Hello, Right now Turbogears biggest problem is no Documentation. We need a strategy from turbogears project to lead a way to better documentation.

What documentation?

  1. First step is to setup epydoc and provide documentation that is available in python code.

 http://epydoc.sourceforge.net/using.html, you have an doc.ini file already  http://groups.google.com/group/turbogears-trunk/browse_thread/thread/c6e4776957b75abc put the results in epydoc.turbogears.com

  1. Provide one source or one template that has all the documentation pages.

Perfect setup is:  http://www.sqlalchemy.org/docs/04/index.html template that builds one page documentation. If this is too hard then merge all wiki pages into one rough1.0doc and let people start working on removing duplicate stuff.

  1. Provide some limits/proper use on creating wiki pages.

Example: Search on widget results in 16 results out of about 1264 pages. (0.79 seconds)

  1. 1.0/CompoundWidgets
  2. 1.0/DataGridWidget
  3. 1.0/IntroductionToWidgets
  4. 1.0/RemoteFormWidgetTutorial
  5. 1.0/RoughDocs/DiveIntoWidgets
  6. 1.0/RoughDocs/ModifyWidgetDefault
  7. 1.0/RoughDocs/WidgetTips
  8. 1.0/RoughDocs/WidgetsOverview
  9. 1.0/SimpleWidgetForm
  1. 1.0/StatelessWidgets
  2. 1.0/WidgetBrowser
  3. 1.0/WidgetList
  4. 1.0/WidgetPackages
  5. 1.0/Widgets
  6. 1.0/WidgetsOverview
  7. 1.0/WidgetsWithJSAndCSS

1.0/Widgets should be only one that holds all subsequent pages as part of the doc.

  1. wiki software? Is this a moinmoin wiki? It seems to be really hard for me to edit it because of syntax. Can we switch to moinmoin wiki? python/debian websites are using it and the syntax is much easier. It allows docbook rendering as well as other options that can potentially be useful. Much more syntax options  http://wiki.debian.org/

Out current wiki has a similar look but the benefit of more user friendly doc software will benefit us more.

  1. Could these changes be implemented before next release? 1.0.x And setup some time frame of what is going to be done, or what can be done now vs next week vs month from now.

Thanks, Lucas

Change History

comment:1 Changed 10 years ago by Chris Arndt

  • Milestone changed from 1.0.4 to 1.1

comment:2 Changed 10 years ago by lszyba1

There has been a conversation in the debian www mailing list and Osamu Aoki from debian.org was able to create an xslt transformation of moinmoin pages to an html/pdf etc. Here is the reference to the results and code:  http://wiki.debian.org/DebianReference The code can be downloaded, the make files changed and we could use it to create html/txt/pdf version of our documentation on a wiki. Some questions to answer are: what version of moinmoin are we running? Is the render as docbook available?

Lucas

comment:3 Changed 10 years ago by Chris Arndt

  • Status changed from new to assigned
  • Owner changed from anonymous to Chris Arndt

Yes, the wiki is moin moin. but I don't think that we well switch to MoinMoin? syntax. See the footnote in  http://docs.turbogears.org/DocHelp#documentation-format-style-guidelines for reasoning.

But I agree that the wiki has too many pages that cover similar topics but do not quite have the same information, so there is considerable overlap and confusion. A first step in consolidating this has been done through ticket #1623.

While I also think that the SQLObject docs are great, I think their scope is not directly comparable to TurboGears'. In the TurboGears docs we try to ingrate information from many projects. Sometimes I think, this was a bad idea, we should have documented what TurboGears adds properly first.

I think I want to make a fresh start with TG 1.1 and move official docs to the SVN repository and build them with Sphinx. Contributed docs would still be hosted on the wiki and integrated into the official docs when appropriate. If you want to help to plan and carry out this effort, you are very welcome!

comment:4 Changed 9 years ago by faide

  • Milestone changed from 1.1 to 1.1.1

comment:5 Changed 9 years ago by faide

  • Milestone changed from 1.6 to 1.5

comment:6 Changed 9 years ago by Chris Arndt

  • Component changed from TurboGears to Documentation

comment:7 Changed 7 years ago by chrisz

  • Status changed from assigned to closed
  • Resolution set to duplicate

moving to Sphinx is now #2521

Note: See TracTickets for help on using tickets.