From Fedora Project Wiki

No edit summary
 
(21 intermediate revisions by 7 users not shown)
Line 1: Line 1:
'''Publican 2''' includes features to automate publishing documents to websites.
{{autolang|base=yes}}


==Preparation==
== Publishing to web.git (Using Publican 2) ==
 
===Prerequisites===
To follow this procedure, you must:
* be a member of the [https://admin.fedoraproject.org/accounts/group/view/docs-publishers docs-publishers group]
* have a local copy of the book checked out from the book's git or SVN repo
 
===Preparation===
<!-- Use <ol> and <li> so we can embed <pre> inside -->
<!-- Use <ol> and <li> so we can embed <pre> inside -->
{{admon/warning|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.}}
<ol><li>Create a local copy of the git repository of the docs.fedoraproject.org website:
<ol><li>Create a local copy of the git repository of the docs.fedoraproject.org website:
<pre>git clone ssh://USERNAME@git.fedorahosted.org/git/docs/web.git</pre>
<pre>git clone ssh://USERNAME@git.fedorahosted.org/git/docs/web.git</pre>
Line 14: Line 24:


db_file: /home/jsmith/fedoradocs/web/fedoradocs.db
db_file: /home/jsmith/fedoradocs/web/fedoradocs.db
toc_path: /home/jsmith/fedoradocs/web/public_html</pre></li>
toc_path: /home/jsmith/fedoradocs/web/public_html
host: http://docs.fedoraproject.org
title: "Fedora Documentation"
search: '<p/>'</pre></li>
<li>Make sure you have the latest version of Publican and the Fedora brand package. As root, run:
<li>Make sure you have the latest version of Publican and the Fedora brand package. As root, run:
<pre>yum update publican publican-fedora</pre>
<pre>yum update publican publican-fedora</pre>
</li></ol>
</li></ol>


==Publishing a document==
===Publishing a document===
{{admon/warning|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.}}
{{admon/warning|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.}}
{{admon/warning|If you are publishing draft documentation, be sure to follow the instructions described at [[Publishing draft documentation]] first.}}
{{admon/warning|If you are publishing draft documentation, be sure to follow the instructions described at [[Publishing draft documentation]] first.}}
{{admon/warning|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_using_Publican|Unpublishing draft documentation]] first.}}


<ol><li>Update your copy of the docs.fedoraproject.org website. In the directory where you keep your local copy of the site, run:
<ol><li>Update your copy of the docs.fedoraproject.org website. In the directory where you keep your local copy of the site, run:
Line 27: Line 43:


<li>Change to the directory where you keep a checked-out copy of the document that you want to publish, then run:
<li>Change to the directory where you keep a checked-out copy of the document that you want to publish, then run:
<pre>publican build --embedtoc --publish --formats epub,html,html-single,pdf --langs LANGUAGE_CODES</pre>
<pre>publican clean</pre> and then run <pre>publican build --embedtoc --publish --formats epub,html,html-single,pdf --langs LANGUAGE_CODES</pre>
where '''''LANGUAGE_CODES''''' is a comma-separated list of the languages in which you want to publish this document. </li>
where '''''LANGUAGE_CODES''''' is a comma-separated list of the languages in which you want to publish this document ( for example, en-US ). </li>
 


<li>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:
<li>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:
Line 38: Line 55:
<pre>publican install_book --site_config PATH_TO_SITE_CONFIG_FILE --lang LANGUAGE_CODE</pre>
<pre>publican install_book --site_config PATH_TO_SITE_CONFIG_FILE --lang LANGUAGE_CODE</pre>
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&nbsp;install_book''' for one language at a time.</li>
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&nbsp;install_book''' for one language at a time.</li>
<li>'''public_html/index.html''' has redirect logic that sends ro-RO requests to '''public_html/ro/index.html''' which does not exist, instead of '''public_html/ro-RO/index.html''' which does exist. After installing books, please check the '''locales''' variable in '''public_html/index.html''' and change '''ro''' to '''ro-RO''' if needed.</li>


<li>Change to the directory in which you keep your local copy of the site and run:
<li>Change to the directory in which you keep your local copy of the site and run:
Line 44: Line 63:
git push</pre></li></ol>
git push</pre></li></ol>


==Removing a document==
===Removing a document===
To remove a document for a particular version of Fedora in a particular language:
To remove a document for a particular version of Fedora in a particular language:


Line 54: Line 73:


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&nbsp;remove_book''' for one language at a time.</li>
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&nbsp;remove_book''' for one language at a time.</li>
<li>'''public_html/index.html''' has redirect logic that sends ro-RO requests to '''public_html/ro/index.html''' which does not exist, instead of '''public_html/ro-RO/index.html''' which does exist. After removing books, please check the '''locales''' variable in '''public_html/index.html''' and change '''ro''' to '''ro-RO''' if needed.</li>


<li>Change to the directory in which you keep your local copy of the site and run:
<li>Change to the directory in which you keep your local copy of the site and run:
Line 60: Line 81:
git push</pre></li>
git push</pre></li>


<li>Publican can only remove the local files and directories on your system, not their record in Git. Run
<li>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 the following command from the directory in which you keep the local copy of the site (the same place you were to run the previous step):
<pre>git status</pre>
<pre>for f in $(git ls-files --deleted); do git rm $f; done </pre>
to look for entries marked as deleted locally but not in git. You must remove these files or directories with
Then push these changes to the remote repo:
<pre>git rm space-separated_list_of_files_and_directories
<pre>git commit -m"rm unused files"
git commit -m"DESCRIPTION_OF_YOUR_CHANGES"
git push</pre>
git push</pre>
{{admon/warning|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.}}</li></ol>
{{admon/warning|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.}}</li></ol>


==Updating a document==
===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.
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_with_Publican#Publishing_a_document|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.
 
===Working with a translated document===
The Fedora Docs Project uses [https://fedora.transifex.net/ Transifex.net] as the docs translation management system. Refer to [[Setting up a document with Transifex]] for instructions on how to prepare, update and publish a translated document using Publican and Transifex.net.
 
== Publishing using Koji (Using Publican >= 4) ==
This is the ''new'' way of publishing Fedora documentation.  This way does away with the web.git repository as used above instead using Koji as a means of managing the documentation in RPMs.
 
=== Preparation ===
First, the publican.cfg file must contain a line making the SRPMs that are built to be for el6:
os_ver: .el6
 
Next, you may have to play around with the formatting of the versions in your revision history which is now used (in Publican 4.x) as the version of the guide.  In particular, in older versions of Publican, revision numbers could be a single number, such as ''42''.  In Publican 4 and later, your revisions should also contain a release, such as ''42-1''.
 
=== Building the SRPM ===
Publican will build the SRPM very easily by issuing the following command:
publican package --lang en-US
 
Obviously the language switch will have to be modified for each language you wish to publish.
 
=== Pushing to Koji ===
To push your SRPM to Koji just issue this command:
koji build el6-docs tmp/rpm/Fedora-Security_Guide-19-web-en-US-19.1-1.el6.src.rpm
 
In the above example I've just pushed the F19 version of the Fedora Security Guide to Koji to be built.  Once Koji builds it, the documentation server will do a ''yum update'' and install any new or updated books at that time.
 
=== Removing a document from Koji ===
 
=== Adding a new guide ===
If your guide hasn't been added to Koji (and this must be done for each Fedora version and language) then you should [https://fedorahosted.org/rel-eng/newticket open a request with Fedora Release Engineering] asking that the RPM name (e.g. Fedora-Security_Guide-19-web-en-US) be added to the el6-docs repo.
 
== Publishing translations (Publican 4) ==
<pre>
publican update_po --firstname=<firstname> --surname=<surname> --email=<email address> --langs=all
publican package --lang=<lang>
koji build el6-docs tmp/rpm/<SRPM>
</pre>


== Publishing updated translations (Publican 4) ==
<pre>
publican add_revision --firstname=<first name> --surname=<surname> --email=<email address> --lang=<lang> --member=<An entry to be added to the revision. Can be specified multiple times.> --revnumber=<revision number>
publican package --lang=<lang>
koji build el6-docs tmp/rpm/<SRPM>
</pre>


[[Category:Documentation tools]]
[[Category:Docs Project process]]
[[Category:Docs Project]]

Latest revision as of 13:34, 22 July 2014

Publishing to web.git (Using Publican 2)

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

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.


  1. 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.
  2. 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
  3. 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/>'
  4. 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 draft documentation, be sure to follow the instructions described at Publishing draft documentation first.
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.


  1. Update your copy of the docs.fedoraproject.org website. In the directory where you keep your local copy of the site, run:
    git pull
  2. Change to the directory where you keep a checked-out copy of the document that you want to publish, then run:
    publican clean
    and 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 ( for example, en-US ).
  3. 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
  4. 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.
  5. public_html/index.html has redirect logic that sends ro-RO requests to public_html/ro/index.html which does not exist, instead of public_html/ro-RO/index.html which does exist. After installing books, please check the locales variable in public_html/index.html and change ro to ro-RO if needed.
  6. 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:

  1. Update your copy of the docs.fedoraproject.org website. In the directory where you keep your local copy of the site, run:
    git pull
  2. 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.
  3. public_html/index.html has redirect logic that sends ro-RO requests to public_html/ro/index.html which does not exist, instead of public_html/ro-RO/index.html which does exist. After removing books, please check the locales variable in public_html/index.html and change ro to ro-RO if needed.
  4. 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
  5. 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 the following command from the directory in which you keep the local copy of the site (the same place you were to run the previous step):
    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.

Working with a translated document

The Fedora Docs Project uses Transifex.net as the docs translation management system. Refer to Setting up a document with Transifex for instructions on how to prepare, update and publish a translated document using Publican and Transifex.net.

Publishing using Koji (Using Publican >= 4)

This is the new way of publishing Fedora documentation. This way does away with the web.git repository as used above instead using Koji as a means of managing the documentation in RPMs.

Preparation

First, the publican.cfg file must contain a line making the SRPMs that are built to be for el6:

os_ver: .el6

Next, you may have to play around with the formatting of the versions in your revision history which is now used (in Publican 4.x) as the version of the guide. In particular, in older versions of Publican, revision numbers could be a single number, such as 42. In Publican 4 and later, your revisions should also contain a release, such as 42-1.

Building the SRPM

Publican will build the SRPM very easily by issuing the following command:

publican package --lang en-US

Obviously the language switch will have to be modified for each language you wish to publish.

Pushing to Koji

To push your SRPM to Koji just issue this command:

koji build el6-docs tmp/rpm/Fedora-Security_Guide-19-web-en-US-19.1-1.el6.src.rpm

In the above example I've just pushed the F19 version of the Fedora Security Guide to Koji to be built. Once Koji builds it, the documentation server will do a yum update and install any new or updated books at that time.

Removing a document from Koji

Adding a new guide

If your guide hasn't been added to Koji (and this must be done for each Fedora version and language) then you should open a request with Fedora Release Engineering asking that the RPM name (e.g. Fedora-Security_Guide-19-web-en-US) be added to the el6-docs repo.

Publishing translations (Publican 4)

publican update_po --firstname=<firstname> --surname=<surname> --email=<email address> --langs=all
publican package --lang=<lang>
koji build el6-docs tmp/rpm/<SRPM>

Publishing updated translations (Publican 4)

publican add_revision --firstname=<first name> --surname=<surname> --email=<email address> --lang=<lang> --member=<An entry to be added to the revision. Can be specified multiple times.> --revnumber=<revision number>
publican package --lang=<lang>
koji build el6-docs tmp/rpm/<SRPM>