As of version 2.0, Publican includes features to automate publishing documents to websites.
Prerequisites
To follow this procedure, you must:
- be a member of the docs-publishers group
- have a local copy of the book checked out from the book's git or SVN repo
Preparation
- Create a local copy of the git repository of the docs.fedoraproject.org website:
git clone ssh://USERNAME@git.fedorahosted.org/git/docs/web.git
Where USERNAME is your FAS username.
- Change into the directory into which you downloaded the web.git repo, and make a copy of homepage.tmp named homepage.cfg:
cp homepage.tmp homepage.cfg
- Edit the homepage.cfg file to provide the absolute paths to the fedoradocs.db file and the public_html directory. For example, if you downloaded the web.git repo to the fedoradocs subdirectory of your home directory, your homepage.cfg file might look like:
# Config::Simple 4.59 # Tue May 11 13:53:03 2010 db_file: /home/jsmith/fedoradocs/web/fedoradocs.db toc_path: /home/jsmith/fedoradocs/web/public_html host: http://docs.fedoraproject.org title: "Fedora Documentation" search: '<p/>'
- Make sure you have the latest version of Publican and the Fedora brand package. As root, run:
yum update publican publican-fedora
Publishing a document
- Update your copy of the docs.fedoraproject.org website. In the directory where you keep your local copy of the site, run:
git pull
- Change to the directory where you keep a checked-out copy of the document that you want to publish, then run:
publican build --embedtoc --publish --formats epub,html,html-single,pdf --langs LANGUAGE_CODES
where LANGUAGE_CODES is a comma-separated list of the languages in which you want to publish this document. - Browse to the publish subdirectory and to the documents themselves inside it to ensure that the documents have built as you expected. In particular, verify:
- the product name is Fedora (note capitalization)
- the version number is correct
- the document title is properly capitalized and spaced: for example, Foo Guide, not foo-guide
- Install the book to the Fedora website:
publican install_book --site_config PATH_TO_SITE_CONFIG_FILE --lang LANGUAGE_CODE
where PATH_TO_SITE_CONFIG_FILE is the path to the homepage.cfg file in your local copy of the docs.fedoraproject.org website, and LANGUAGE_CODE is the language in which you are publishing the document. Note that you can only run publican install_book for one language at a time. - Change to the directory in which you keep your local copy of the site and run:
git add . git commit -m "DESCRIPTION_OF_YOUR_CHANGES" git push
Removing a document
To remove a document for a particular version of Fedora in a particular language:
- Update your copy of the docs.fedoraproject.org website. In the directory where you keep your local copy of the site, run:
git pull
- Change to the directory where you keep a checked-out copy of the document that you want to remove, then run:
publican remove_book --site_config PATH_TO_SITE_CONFIG_FILE --lang LANGUAGE_CODE
where PATH_TO_SITE_CONFIG_FILE is the path to the homepage.cfg file in your local copy of the docs.fedoraproject.org website, and LANGUAGE_CODE is the language in which you are removing the document. Note that you can only run publican remove_book for one language at a time. - Change to the directory in which you keep your local copy of the site and run:
git add . git commit -m "DESCRIPTION_OF_YOUR_CHANGES" git push
- Publican can only remove the local files and directories on your system, not their record in Git. To remove the deleted files from your local Git repo, run:
for f in $(git ls-files --deleted); do git rm $f; done
Then push these changes to the remote repo:
git commit -m"rm unused files" git push
Updating a document
To update a document previously published in a particular language for a particular version of Fedora, change into the directory in which you keep a checked-out copy of the document, then run publican install_book, as if you were installing it for the first time. Publican automatically replaces the old version with the new one.