Ticket #305 (closed todo: fixed)

Opened 8 years ago

Last modified 7 years ago

Fix online documentation

Reported by: whiteknight Owned by:
Priority: normal Milestone: 1.0
Component: website Version:
Severity: medium Keywords: website docs web
Cc: Language:
Patch status: Platform:


We need to fix the online portion of our documentation, as a logical continuation of #237. Some requirements:

1) The "docs" link on parrot.org should not point to the old page at parrotcode.org 2) We need to review the documents that get posted online, and make sure all the important documents are being updated on the website 3) We need to make sure docs/book/ is being posted online too 4) Probably need to update the automatically-generated HTML to match the theme of the rest of the website.


rebuild-docs-website.sh Download (396 bytes) - added by Infinoid 8 years ago.
Cron job for generating docs.parrot.org content (recommend running once an hour)

Change History

Changed 8 years ago by coke

Here's a plan:

a) have 'make html' generate the files statically. b) for each release, copy those generated files out to parrot.org (some of us have ssh access to do this.).

Then we can keep a directory for "devel", "stable", "0.9.1", etc. (with some being symlinks to others as appropriate.), we can then rotate out the old docs as necessary. (We seem to have the ability to create subdirectories under the drupal install that we can then link to.)

Anyone needing bleeding edge docs can use svn, since they'll already have it.

At that point, most of parrotcode.org can be shut down. Anything remaining should either go into the repository or into a page somewhere on *.parrot.org

Changed 8 years ago by coke

For bonus points, have the 'make html' step working as desired prior to the next release.

Changed 8 years ago by coke

Note, allison's recent work on 'make html' has made it quite pretty; after 'make html', you'll need docs/html and docs/resources copied somewhere.

Talking with allison on IRC, she wants to use docs.parrot.org -- which doesn't currently exist. Need the host/site setup on the parrotvm server, then we can proceed.

Changed 8 years ago by allison

Yes, submit a ticket to the support alias at osuosl.org requesting the new DNS/directory. (It's on my TODO list, but I haven't had time.) It'll be a simple static (generated) html site.

Changed 8 years ago by coke

  • owner set to coke

Changed 8 years ago by coke

Ticket requested: [support.osuosl.org #6281]

Changed 8 years ago by coke

docs.parrot.org now exists (but is empty)

Changed 8 years ago by Infinoid

Cron job for generating docs.parrot.org content (recommend running once an hour)

Changed 8 years ago by Infinoid

I've attached a script suitable for running from cron periodically. It cleans and updates a parrot checkout, configures it, does "make html" and rsyncs it to $WEBROOT/. Please adjust the variables at the top of the script to point at the webroot and a parrot svn checkout.

Hope it helps.

Changed 8 years ago by coke

  • milestone changed from 0.9.1 to 1.0

Infinoid++ poked me into putting the 0.9.1 docs online. Here's the current URL(s) to get to the 0.9.1 docs:

 http://docs.parrot.org/parrot/devel/html/  http://docs.parrot.org/parrot/0.9.1/html/

the top level parrot is to allow us some wiggle room to add other docs to the site. (parrot.org? foundation. parrot/ ? the vm)

devel is a symlink to 0.9.1. the extra html/ at the end corresponds to docs/html; there is also a resources/ at that level that corresponds to docs/resources.

Changed 8 years ago by coke

  • owner coke deleted

Changed 8 years ago by coke

Removed "devel" alias, as particle++ has pointed out that after 1.0, according to chromatic's support policy, there are no development releases anymore, and devel is probably better suited to mean "svn HEAD" at that point.

Changed 8 years ago by allison

  • status changed from new to closed
  • resolution set to fixed

Satisfied with current docs.parrot.org. The 'make html' target has been updated so the 1.0 generated docs will have a nice TOC as the front page. Resolving ticket.

Changed 7 years ago by coke

  • keywords web added
Note: See TracTickets for help on using tickets.