Prerequisites

have a local copy of the book checked out from the book's git or SVN repo

Preparation

Documents produced with versions of Publican prior to 2.5 are not compatible with the current website structure. Always make sure that you have the latest version of Publican installed before you publish documents.

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.

Large download This download will take some time, even on fast connections.

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:

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

Publican now controls the directory structure and the SQLite database that manages the site and its tables of contents. Do not add or remove directories from the directory tree manually as we did in the past.

If you are publishing the final version of documentation that was first published in the "Draft Documentation" category, be sure to follow the instructions described at Unpublishing draft documentation first.

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:

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:

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

A "git rm" command gone wrong can cause widespread damage to the documentation site. If you are not absolutely sure of what you are doing, ask for help.

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 follow the instructions in the Publishing a document procedure to build, install, and push the book, just as if you were installing it for the first time. Publican automatically replaces the old version with the new one.