Using reST + Sphinx for documentation?

Main development forum.

Using reST + Sphinx for documentation?

Postby kimmov » Fri Jul 24, 2009 9:53 pm

Currently our documentation in source tree is in several formats:
  • user manual is docbook
  • most developer docs are HTML
  • user docs (other than manual) and some developer docs are plain text
Plain text isn't very good looking and there are issues showing plain text documents for users. I'm wondering if we could use reST markup instead of plaintext and HTML. We can generate other formats when needed (for releases, web pages?). Sphinx generates nice HTML/PDF documentation from reST. All current Python documentation is generated with it.

NOTE: I'm not suggesting changing user manual, just other documentation in other formats.
kimmov
 
Posts: 562
Joined: Thu Sep 11, 2008 8:51 pm
Location: Finland

Re: Using reST + Sphinx for documentation?

Postby gerundt » Sun Jul 26, 2009 10:45 am

Sounds interessting! I think at a system like this for contributer file too! So we have a plan text file in the sources but a HTML version for the users in a release...
gerundt
Site Admin
 
Posts: 193
Joined: Wed Sep 24, 2008 8:47 am
Location: Germany

Re: Using reST + Sphinx for documentation?

Postby kimmov » Sun Jul 26, 2009 11:28 am

Yep, I'd prefer HTML over plain text as user documents. And based on what I've read so far we can produce "site" from the documentation with table of contents, links between docs etc. Instead of separate text files user needs to open separately.

Same for developer docs - we don't need those hand-written index pages. Though I believe most developers will still look at the plain text versions in the SVN tree. But editing reST/plain text is much easier than editing HTML (IMHO).
kimmov
 
Posts: 562
Joined: Thu Sep 11, 2008 8:51 pm
Location: Finland

Re: Using reST + Sphinx for documentation?

Postby gerundt » Sun Nov 08, 2009 12:41 pm

Ok, I tested Sphinx and I like it! :)

What about this idea:
* We create a "Cookbook" subfolder in "Docs\Developers" folder.
* We port all important HTML files to reST text files in this subfolder.
* We create a Sphinx project for the "WinMerge Cookbook".
* We can later put this cookbook at the homepage too.
gerundt
Site Admin
 
Posts: 193
Joined: Wed Sep 24, 2008 8:47 am
Location: Germany

Re: Using reST + Sphinx for documentation?

Postby kimmov » Sun Nov 15, 2009 12:42 pm

What do you mean by "important" files? I can't think of any files I wouldn't want to include to user- or developer-documentation. If there are such files aren't those files then just unneeded and can be removed?

I think we can just create one "developer guide" project from all current developer documentation. And another project from user docs we can distribute with releases. Would make atleast the release notes editing easier.
kimmov
 
Posts: 562
Joined: Thu Sep 11, 2008 8:51 pm
Location: Finland

Re: Using reST + Sphinx for documentation?

Postby gerundt » Sun Nov 15, 2009 12:57 pm

kimmov wrote:What do you mean by "important" files? I can't think of any files I wouldn't want to include to user- or developer-documentation. If there are such files aren't those files then just unneeded and can be removed?


For me is "Developers\readme-developers-MakePatchDirs.html" unimportant and I am not shure, if I really want to port "Developers\Plugins.html"...
gerundt
Site Admin
 
Posts: 193
Joined: Wed Sep 24, 2008 8:47 am
Location: Germany

Re: Using reST + Sphinx for documentation?

Postby kimmov » Sun Nov 15, 2009 6:56 pm

gerundt wrote:For me is "Developers\readme-developers-MakePatchDirs.html" unimportant and I am not shure, if I really want to port "Developers\Plugins.html"...

Those files should be just removed. We'll drop the plugins support so we don't need docs for creating them. And readme-developers-MakePatchDirs.html is Perry's personal workflow years back. Seems to talk about CVS. So we can just remove it too.
kimmov
 
Posts: 562
Joined: Thu Sep 11, 2008 8:51 pm
Location: Finland

Re: Using reST + Sphinx for documentation?

Postby gerundt » Sat Feb 06, 2010 1:53 pm

I submit a first raw version of a Sphinx documentation as patch: #2947040 - WinMerge Developer Cookbook with reST + Sphinx
gerundt
Site Admin
 
Posts: 193
Joined: Wed Sep 24, 2008 8:47 am
Location: Germany


Return to Developers

Who is online

Users browsing this forum: No registered users and 3 guests