On 06/25/2010 07:20 AM, Karsten Wade wrote: > While I've been waiting to see how the Zikula deployment went with > Fedora Insight, we've finally seen a better update to > docs.fedoraproject.org by using the native Publican site building > tools. I've waited to push forward with a CMS solution for Fedora > Docs until we had a working solution to design against. > > While Publican gives us a way to build a nicely organized tree of > content, it doesn't give other capabilities. I don't know of any > plans to include this sort of thing in Publican natively: > > * Ability to trigger (re)builds from source repositories via a webUI. > > * Workflow control, either by group (writers, editors, publishers), or > specific roles like that but per document (I can write this one, I > can edit yours, and I can push hers to publish after you edit it.) > > * WYSIWYG editor for DocBook XML from source repository. > > Basically, we still have very high barriers to move from "edit stuff > on the wiki" to "manage a full guide on DocBook XML." The main > purpose for a CMS is to get the ability to publish and tweak > docs.fedoraproject.org out of the hands of a very few, very busy > people, and in to the hands of just about anyone that this team wants > to authorize to do work there. > > Talking in the meeting yesterday, I threw out some ideas around this > and agreed to bring those here. I'm still interested in helping drive > a CMS-like project for Docs. > > So I'll throw out a proposal to get us started. This proposal exists > partially because of our commitment to using Publican to publish. > Another option is to use Publican only to generate documents, which > are then loaded and versioned in a CMS e.g. Zikula or Drupal. Working > under this other option would be more like the CMS experience others > have -- you either work in the native editor, or you upload documents > you created elsewhere. > > == Docs CMS == > > === Terms === > > * Publican is a command-line toolchain for building books as HTML, > PDF, Epub, Text, etc. and publishing them to a static website with > a navigation sidebar. It uses books written in DocBook XML that > exist as installable RPM packages. > > * Beacon is a wysiwyg, webUI editor that has been extended to > support DocBook XML editing. > > * Fedora Hosted (fh.o) is a hosting solution that is the source > repository for Fedora Docs. Books primarily use Subversion or git > as source control manager (SCM). > > * WebUI is a generic term for the web user interface that we have to > write or configure to wrap around and perform certain functions > for this CMS. For example, it can present a button to a person > with publishing privileges, when pressed triggers of a Publican > build on the backend. This webUI could be custom code written in > Python and TurboGears, or it could be Drupal with a few custom > modules. > > * A reader has the ability to read the website anonymously. No > credentials are required. > > * A writer belongs to a 'doc-writers' group and also belong to the > group associated with each document, e.g. 'gitinstall-guide'. > Being in the 'doc-writers' group is a prerequisite that exposes > the Beacon editor function. > > * An editor is the same as a writer, performing a different role in > the process. > > * A publisher is a member of the 'doc-publishers' group, which gives > the permission to trigger special functions in the webUI - build a > doc, rebuild a doc, install a doc package, etc. > > === WebUI architecture === > > Functions: > 0. Read > 1. Write/edit > 2. Publish > > 0. Read > a. Publican produces pages and navigation at docs.fp.org. > i. These pages are static and not wrapped by the webUI. > b. Readers use Publican's navigation to read guides. > > 1. Write/edit > a. Writer clicks "Check out document for editing" (this is NOT a > locking mechanism.) > i. Clicking check out triggers a 'git clone' of the document > repo. > ii. The cloned git repo is then branched locally to the webUI > server, for example 'git branch quaid-20100224-UUID' with a > short, sequential UUID such as 'AA00'. > iii. Beacon is then opened using the local file check out of the > XML. > iv. Beacon saves work only in the files in the cloned repo. An > added functionality could trigger 'git commit' on save, but > this might cause too many commits without a log message. > v. The writer's training includes knowing to commit on a regular > basis, in a granular fashion, when one or more edit+saves > makes a good bundle for a commit. Clicking on "Commit > changes" opens a log summary window, then a 'git commit -m > "$dump_from_log_summary_window" is done on the local repo. > vi. A writer's session should persist. When the writer returns > and still has local changes committed but not pushed to the > master git repo, the writer is offered those files to > continue work on, or to checkout a different document. > vii. When the writer is done with the writing session, the > writer clicks a "Check in document to main repository". > This triggers a 'git push' to the master repository. > > 2. Publish > a. Publisher selects a document and version from a > dropdown/checklist menu. > i. This list is generated from installed packages on docs.fp.o, > information extracted using 'rpm' commands. > b. Publisher clicks "Rebuild and publish document." > i. A koji scratchbuild is triggered, which grabs the latest > source from the upstream repository and builds a package. > ii. When the build is done, the package is installed from koji > using yum. > c. Publisher adds a new document to the publish list. > i. Document must exist as package in koji already. > ii. Publisher uses a Moksha widget to identify the meta-package > OR a specific package name and version are supplied > manually. > iii. Package is installed on docs.fedoraproject.org. > iv. Cached list of installed packages is refreshed to update > document and version dropdown/checklist menus. > > <eof> > > - Karsten > Another writer and I started coding up a project to do this. The main issue we hit was time, which is what killed it for us. This isn't a difficult project but it would take at least 6 months of full time development. Chris -- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
