Conversion of docs to .rst

[p-static]

As discussed on the mailing list, I'll be reformatting the docs in the source tree as reStructuredText.

[p-static]

docs/stats.txt, converted t rST

[p-static]

I've just attached an example document (stats.txt) converted to rST format. Here's an HTML render of that file: ​http://p-static.net/stats.html

[p-static]

Patch against latest darcs checkout

[p-static]

Just attached docs-txt-rst-conversion.patch, which has all the .txt files under docs/ converted to rST. Corrections and suggestions on the formatting are welcome.

I've also generated a set of html documents from the files, using rst2html.py. You can see the result here: ​http://p-static.net/tahoe-docs/

[p-static]

Seems like Trac has built-in support for .rst - ​http://trac.edgewall.org/wiki/WikiRestructuredText

With this, we wouldn't even need a separate conversion to html step - it looks like Trac will even render .rst in the source viewer directly, if we can figure out the darcs equivalent for setting a svn property.

[freestorm]

Replying to p-static:

Just attached docs-txt-rst-conversion.patch, which has all the .txt files under docs/ converted to rST. Corrections and suggestions on the formatting are welcome.

I've also generated a set of html documents from the files, using rst2html.py. You can see the result here: ​http://p-static.net/tahoe-docs/

It sound fine for me.

Maybe we need to add the darc revision in bottom of file, so if you print, you can know from which revision is the file.

Like I did with my php script in bottom of file (just note that script is not finished and I need to reformat the revision output):​configuration.txt

[p-static]

That'd be pretty useful. We could do it in the conversion script pretty easily by writing a text file with the version info (and whatever else we want in a footer?) and then using rST's include directive to pull that in. It'd tie us to using a conversion script, but that probably would have happened anyway.

[davidsarah]

Replying to p-static:

Seems like Trac has built-in support for .rst - ​http://trac.edgewall.org/wiki/WikiRestructuredText

With this, we wouldn't even need a separate conversion to html step - it looks like Trac will even render .rst in the source viewer directly, if we can figure out the darcs equivalent for setting a svn property.

According to ​this post, darcs has no direct equivalent to svn properties. I don't know whether ​TracDarcs has any way to configure the mapping of filetypes to MIME types.

[zooko]

renamed the files from .txt to .rst, fixed a formatting issue in backdoors.rst, added NEWS entry, added darcs patch description (commit log entry)

[zooko]

Brian: please review in order to check for any major documentation corruption before we commit this.

[zooko@…]

In 8143183e39733786:

docs: convert all .txt docs to .rst thanks to Ravi Pinjala
fixes #1225

[davidsarah]

The files in docs/frontends have not been converted.

[davidsarah]

... and the other subdirectories, of which docs/specifications is probably most important.

[zooko]

p-static told me in email that he hopes to fix this in the next couple of days for the 1.8.1 release.

[p-static]

Just to keep folks updated on this: I'll be adding the work to a Github repo as it goes. When I'm done, I'll attach a complete patch to this issue.

​http://github.com/p-static/tahoe-lafs

[p-static]

conversion of specifications/ and frontends/

[p-static]

Just attached the next part of the conversion; this patch covers the files in docs/specifications/ and docs/frontends/. (This corresponds to ​http://github.com/p-static/tahoe-lafs/commit/37b543fc5168437653ab0f1b867a9bff7ada721c) In case I don't finish in time for 1.8.1, this is a logical unit of work to add to it.

I renamed the files in this patch, not realizing that it would duplicate the contents of each file twice in the diff. >_< For the next one, I'll probably go back to leaving them named *.txt, and letting whoever applies the patch rename the files.

As for the rest of the conversion, the only remaining directories are historical/ and proposed/. I'm planning to finish proposed/ this weekend, but I'm wondering if we actually care about converting the historical docs. Anybody especially want to see them in rST format?

[warner]

hm, if you're doing this in darcs, you might consider using two separate patches: the first would rename *.txt to *.rst, the second would make the actual rST changes to the contents. That might cause the tools to work better.

Or it might not, I'm not sure..

[zooko]

I think p-static's problem with the file contents appearing twice in each diff were from his use of git. When using darcs, you use darcs mv to rename the file and then you can record that mv along with the edits to the contents of the file in a single patch. Whoever commits this to trunk, please make sure it is an mv patch and not a patch that removes the old file and adds a new file!

[zooko]

p-static's patch was applied in 8143183e39733786. p-static: I agree that docs/historical can remain untouched, Did you update docs/proposed?

[p-static]

Oh, now I remember what happened. I started looking at proposed/, but then realized that most of the files there haven't been touched in a few years, so I didn't know what their status actually was. Then I completely forgot to update this bug, sorry about that D:

I think we can go ahead and mark this as resolved, unless some of those proposed specs are still active.

[p-static]

It seems like the second part of the patch (that converted frontends/ and specifications/) may not have been applied.

​http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/frontends/

Oddly enough, Trac tries to redirect me to the .rst versions of the files, and then gives a 404. No idea what's going on there.

[zooko]

Replying to p-static:

It seems like the second part of the patch (that converted frontends/ and specifications/) may not have been applied.

​http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/frontends/

Oddly enough, Trac tries to redirect me to the .rst versions of the files, and then gives a 404. No idea what's going on there.

I told apache (which is the front-end) to redirect:

    # make 301 /trac/tahoe -> /trac/tahoe-lafs
    RedirectMatch permanent ^/trac/tahoe$ http://tahoe-lafs.org/trac/tahoe-lafs
    RedirectMatch permanent ^/trac/tahoe/(.*) http://tahoe-lafs.org/trac/tahoe-lafs/$1

    # make a bare http://tahoe-lafs.org send users to the Tahoe trac instance
    RedirectMatch permanent ^/$ http://tahoe-lafs.org/trac/tahoe-lafs

    # 302 all .txt to .rst in the source tree
    # e.g. http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/known_issues.txt
    RedirectMatch permanent ^/source/tahoe-lafs/(.*).txt http://tahoe-lafs.org/source/tahoe-lafs/$1.rst

[david-sarah@…]

In 1d5c705201fdcf0e:

Move .txt files in docs/frontends and docs/specifications to .rst. refs #1225

[david-sarah@…]

In 7da1885531508c25:

docs/specifications/mutable.rst: correct the magic string for v1 mutable containers. refs #1225

[davidsarah]

Replying to david-sarah@…:

In 7da1885531508c25:

docs/specifications/mutable.rst: correct the magic string for v1 mutable containers. refs #1225

This was meant to refer to ticket:1277#comment:3.

[david-sarah@…]

In 458b2de08bb084e5:

docs/specifications/dirnodes.rst: fix references to mutable.rst. refs #1225

[david-sarah@…]

In 5d612c87abe71fdd:

Update hyperlinks between docs, and linkify some external references. refs #1225

[david-sarah@…]

In 5ce5faf0af485eeb:

More specific hyperlink to architecture.rst from helper.rst. refs #1225

[david-sarah@…]

In 341cad80ff30ffd2:

Fix a link from webapi.rst to FTP-and-SFTP.rst. refs #1225

[david-sarah@…]

In 5f73c27b23007ee4:

Fix a link from uri.rst to dirnodes.rst. refs #1225

[davidsarah]

TODO: write things that look like URLs but aren't (e.g. the strport examples in ​http://tahoe-lafs.org/trac/tahoe-lafs/browser/trunk/docs/configuration.rst) in a way that stops them from being linkified.

[david-sarah@…]

In 64a4ef5966d8f743:

docs/known_issues.rst: fix an external link. refs #1225

[david-sarah@…]

In e35cbb7aef3728fb:

docs/known_issues.rst: fix title and linkify another URL. refs #1225

[davidsarah]

This is done, except for a NEWS entry. p-static's second patch was applied in 2100273ce3436877.

[david-sarah@…]

In 1190ce614303b6fb:

NEWS: 'top' for node processes, WUI formatting, removal of GUI apps, documentation updates, foolscap dependency. refs #174, #1219, #1225