#1225 closed enhancement (fixed)

Conversion of docs to .rst

Reported by: p-static Owned by: davidsarah
Priority: minor Milestone: 1.8.2
Component: documentation Version: 1.8.0
Keywords: docs news-needed Cc:
Launchpad Bug:

Description

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

Attachments (4)

stats.txt (14.2 KB) - added by p-static at 2010-10-13T06:30:35Z.
docs/stats.txt, converted t rST
docs-txt-rst-conversion.patch (130.7 KB) - added by p-static at 2010-10-14T07:49:17Z.
Patch against latest darcs checkout
docs-txt-to-rst.darcs.patch (138.0 KB) - added by zooko at 2010-10-15T05:36:34Z.
renamed the files from .txt to .rst, fixed a formatting issue in backdoors.rst, added NEWS entry, added darcs patch description (commit log entry)
docs-txt-rst-conversion-ii.patch (444.2 KB) - added by p-static at 2010-10-29T05:45:43Z.
conversion of specifications/ and frontends/

Download all attachments as: .zip

Change History (43)

Changed at 2010-10-13T06:30:35Z by p-static

docs/stats.txt, converted t rST

comment:1 Changed at 2010-10-13T06:31:32Z by 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

Changed at 2010-10-14T07:49:17Z by p-static

Patch against latest darcs checkout

comment:2 follow-up: Changed at 2010-10-14T07:55:54Z by 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/

comment:3 follow-up: Changed at 2010-10-14T17:21:12Z by 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.

comment:4 in reply to: ↑ 2 Changed at 2010-10-14T21:38:17Z by 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

comment:5 Changed at 2010-10-15T02:16:21Z by 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.

comment:6 in reply to: ↑ 3 Changed at 2010-10-15T03:29:58Z by 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.

Changed at 2010-10-15T05:36:34Z by 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)

comment:7 Changed at 2010-10-15T05:37:13Z by zooko

  • Keywords review-needed added
  • Owner changed from somebody to warner

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

comment:8 Changed at 2010-10-15T05:51:31Z by zooko@…

  • Resolution set to fixed
  • Status changed from new to closed

In 8143183e39733786:

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

comment:9 Changed at 2010-10-23T04:33:16Z by davidsarah

  • Resolution fixed deleted
  • Status changed from closed to reopened

The files in docs/frontends have not been converted.

comment:10 Changed at 2010-10-23T04:34:54Z by davidsarah

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

comment:11 Changed at 2010-10-27T02:10:23Z by p-static

  • Owner changed from warner to p-static
  • Status changed from reopened to new

comment:12 Changed at 2010-10-28T06:14:14Z by 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.

comment:13 Changed at 2010-10-29T03:18:21Z by 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

Changed at 2010-10-29T05:45:43Z by p-static

conversion of specifications/ and frontends/

comment:14 Changed at 2010-10-29T05:50:53Z by 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?

comment:15 Changed at 2010-10-29T21:31:41Z by 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..

comment:16 Changed at 2010-10-29T23:06:35Z by 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!

comment:17 Changed at 2010-11-18T06:43:13Z by zooko

  • Milestone changed from soon to 1.8.1

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

comment:18 Changed at 2010-11-18T07:06:51Z by 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.

comment:19 Changed at 2010-11-18T07:52:54Z by zooko

  • Resolution set to fixed
  • Status changed from new to closed

comment:20 follow-up: Changed at 2010-12-04T08:22:48Z by p-static

  • Resolution fixed deleted
  • Status changed from closed to reopened

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.

comment:21 in reply to: ↑ 20 Changed at 2010-12-04T12:32:49Z by 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

comment:22 Changed at 2010-12-12T01:33:49Z by david-sarah@…

In 1d5c705201fdcf0e:

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

comment:23 follow-up: Changed at 2010-12-12T01:44:22Z by david-sarah@…

In 7da1885531508c25:

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

comment:24 in reply to: ↑ 23 Changed at 2010-12-12T01:52:32Z by 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.

comment:25 Changed at 2010-12-12T01:58:07Z by david-sarah@…

In 458b2de08bb084e5:

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

comment:26 Changed at 2010-12-12T05:43:48Z by davidsarah

  • Keywords docs added

comment:27 Changed at 2010-12-12T05:48:01Z by david-sarah@…

In 5d612c87abe71fdd:

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

comment:28 Changed at 2010-12-12T05:57:13Z by david-sarah@…

In 5ce5faf0af485eeb:

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

comment:29 Changed at 2010-12-12T06:05:41Z by david-sarah@…

In 341cad80ff30ffd2:

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

comment:30 Changed at 2010-12-12T06:19:02Z by david-sarah@…

In 5f73c27b23007ee4:

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

comment:31 Changed at 2010-12-12T06:42:15Z by 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.

comment:32 Changed at 2010-12-12T06:54:36Z by david-sarah@…

In 64a4ef5966d8f743:

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

comment:33 Changed at 2010-12-12T07:01:05Z by david-sarah@…

In e35cbb7aef3728fb:

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

comment:34 Changed at 2010-12-31T22:15:21Z by davidsarah

  • Keywords news-needed added; review-needed removed
  • Owner changed from p-static to davidsarah
  • Status changed from reopened to new
  • Version changed from n/a to 1.7.1

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

comment:35 Changed at 2010-12-31T22:15:31Z by davidsarah

  • Status changed from new to assigned

comment:36 Changed at 2010-12-31T22:15:44Z by davidsarah

  • Version changed from 1.7.1 to 1.8.0

comment:37 Changed at 2011-01-06T01:28:43Z by david-sarah@…

In 1190ce614303b6fb:

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

comment:38 Changed at 2011-01-06T21:21:26Z by warner

  • Milestone changed from 1.8.1 to soon

comment:39 Changed at 2011-01-06T23:49:10Z by davidsarah

  • Milestone changed from soon to 1.8.2
  • Resolution set to fixed
  • Status changed from assigned to closed
Note: See TracTickets for help on using tickets.