[documentation-guide] Documented how to publish a document using Koji.
jhradile
jhradile at fedoraproject.org
Sat Mar 22 03:56:32 UTC 2014
commit df44444732abce9c24549c7e57642f0652bf34ee
Author: Jaromir Hradilek <jhradile at redhat.com>
Date: Sat Mar 22 03:47:58 2014 +0100
Documented how to publish a document using Koji.
en-US/publican.xml | 193 ++++++++++------------------------------------------
1 files changed, 36 insertions(+), 157 deletions(-)
---
diff --git a/en-US/publican.xml b/en-US/publican.xml
index 08fe235..c752590 100644
--- a/en-US/publican.xml
+++ b/en-US/publican.xml
@@ -142,10 +142,8 @@
</table>
</section>
<section id="sect-publican-validating">
- <title>Validating XML Code</title>
- <para>
- <remark>Hic sunt leones.</remark>
- </para>
+ <title>Validating a Document</title>
+ <remark>Hic sunt leones.</remark>
</section>
<section id="sect-publican-building">
<title>Building a Document</title>
@@ -255,179 +253,60 @@
</section>
<section id="sect-publican-publishing">
<title>Publishing a Document</title>
- <para>
- Publishing a document to the Fedora Documentation website isn't that difficult when <application>Publican</application> is doing the heavy lifting. It is assumed that you already have the repository cloned on the computer that <application>Publican</application> will be working from and that your configuration is complete.
- </para>
- <warning>
- <para>
- 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.
- </para>
- </warning>
- <section id="sect-publican-publishing-preparing">
- <title>Preparing Your System</title>
+ <section id="sect-publican-publishing-adding">
+ <title>Adding a New Document</title>
+ <remark>Hic sunt leones...</remark>
+ </section>
+ <section id="sect-publican-publishing-updating">
+ <title>Updating a Document</title>
<para>
- Before we start building your documents into the proper formats for user consumption we need to pull down the webpage source which you'll later add your document into and commit. The following procedure will instruct you on how to do this.
+ To publish your document on the <ulink url="http://docs.fedoraproject.org/">Fedora Documentation</ulink> website, complete the following steps:
</para>
- <itemizedlist>
- <listitem>
+ <procedure id="proc-publican-publishing">
+ <step>
<para>
- Create a local copy of the git repository of the docs.fedoraproject.org website: <command>git clone ssh://USERNAME@git.fedorahosted.org/git/docs/web.git</command> where <literal>USERNAME</literal> is your FAS username.
+ Make sure that the <filename>publican.cfg</filename> file in the main directory of your document contains the following line:
</para>
- <note>
- <para>
- This download will take some time, even on fast connections.
- </para>
- </note>
- </listitem>
- <listitem>
+ <programlisting>os_ver: .el6</programlisting>
+ </step>
+ <step>
<para>
- Change into the directory into which you downloaded the <literal>web.git</literal> repo, and make a copy of <literal>homepage.tmp</literal> named <literal>homepage.cfg</literal>:<command>cp homepage.tmp homepage.cfg</command>
+ Update the <filename><replaceable>language</replaceable>/Revision_History.xml</filename> file to ensure that the document has a unique revision number. To create a new entry in the revision history, use the following command:
</para>
- </listitem>
- <listitem>
+ <screen><command>publican add_revision --lang <replaceable>language</replaceable> \</command>
+ <command>--firstname <replaceable>first_name</replaceable> --surname <replaceable>surname</replaceable> --email <replaceable>email</replaceable> \</command>
+ <command>--member "<replaceable>description</replaceable>"</command></screen>
<para>
- Edit the <literal>homepage.cfg</literal> file to provide the absolute paths to the <literal>fedoradocs.db</literal> file and the <literal>public_html</literal> directory. For example, if you downloaded the <literal>web.git</literal> repo to the <literal>fedoradocs</literal> subdirectory of your home directory, your homepage.cfg file might look like:
+ Replace <replaceable>language</replaceable> with a selected language code, <replaceable>first_name</replaceable> with your given name, <replaceable>surname</replaceable> with your surname, <replaceable>email</replaceable> with your email address, and <replaceable>description</replaceable> with a brief description of your changes.
</para>
- <programlisting>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:</programlisting>
- </listitem>
- <listitem>
- <para>
- Make sure you have the latest version of Publican and the Fedora brand package. As root, run: <command>yum update publican publican-fedora</command>
- </para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="sect-publican-publishing-publishing">
- <title>Publishing a Document on the Web</title>
- <warning>
- <para>
- 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.
- </para>
- </warning>
- <warning>
- <para>
- If you are publishing draft documentation, be sure to follow the instructions described at Publishing draft documentation first.
- </para>
- </warning>
- <warning>
- <para>
- 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.
- </para>
- </warning>
- <note>
- <title>Incorrect product or version</title>
- <para>If the publish results in an incorrect product or version, check the
- <filename><replaceable>Type</replaceable>_Info.xml</filename> to ensure
- the <literal>productname</literal> and <literal>productversion</literal>
- elements match the desired output. If they are correct, check the
- <filename>publican.cfg</filename> file for lines that begin with
- <literal>version</literal> or <literal>web_version_label</literal>. Delete
- those lines, if they exist.
- </para>
- </note>
- <itemizedlist>
- <listitem>
+ </step>
+ <step>
<para>
- Update your copy of the docs.fedoraproject.org website. In the directory where you keep your local copy of the site, run: <command>git pull</command>
+ Package your document as a source RPM (SRPM):
</para>
- </listitem>
- <listitem>
+ <synopsis><command>publican package --lang <replaceable>language</replaceable></command></synopsis>
<para>
- Change to the directory where you keep a checked-out copy of the document that you want to publish, then run: <command>publican build --embedtoc --publish --formats epub,html,html-single,pdf --langs <replaceable>LANGUAGE_CODES</replaceable></command> where <literal>LANGUAGE_CODES</literal> is a comma-separated list of the languages in which you want to publish this document.
+ Replace <replaceable>language</replaceable> with a selected language code. This command stores the newly created SRPM package in the <filename class="directory">tmp/rpm/</filename> directory and prints the absolute path to this file to standard output. If you intend to publish your document in more than one language, repeat this step with a different language code.
</para>
- </listitem>
- <listitem>
+ </step>
+ <step>
<para>
- 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 <literal>Fedora</literal> (note capitalization), the version number is correct, the document title is properly capitalized and spaced: for example, <literal>Foo Guide</literal>, not <literal>foo-guide</literal>
+ Push the SRPM package created in the previous step to Koji:
</para>
- </listitem>
- <listitem>
+ <synopsis><command>koji build el6-docs <replaceable>package_name</replaceable></command></synopsis>
<para>
- Install the book to the Fedora website: <command>publican install_book --site_config PATH_TO_SITE_CONFIG_FILE --lang LANGUAGE_CODE</command> where <literal>PATH_TO_SITE_CONFIG_FILE</literal> is the path to the <literal>homepage.cfg</literal> file in your local copy of the docs.fedoraproject.org website, and <literal>LANGUAGE_CODE</literal> is the language in which you are publishing the document. Note that you can only run <command>publican install_book</command> for one language at a time.
+ Replace <replaceable>package_name</replaceable> with a path to the SRPM package.
</para>
- </listitem>
- <listitem>
- <para>
- Change to the directory in which you keep your local copy of the site and run:
- </para>
- <screen><command>git add .</command>
-<command>git commit -m "DESCRIPTION_OF_YOUR_CHANGES"</command>
-<command>git push</command></screen>
- </listitem>
- </itemizedlist>
+ </step>
+ </procedure>
</section>
<section id="sect-publican-publishing-removing">
- <title>Removing a Document from the Web</title>
- <para>
- To remove a document for a particular version of Fedora in a particular language:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Update your copy of the docs.fedoraproject.org website. In the directory where you keep your local copy of the site, run: <command>git pull</command>
- </para>
- </listitem>
- <listitem>
- <para>
- Change to the directory where you keep a checked-out copy of the document that you want to remove, then run: <command>publican remove_book --site_config PATH_TO_SITE_CONFIG_FILE --lang LANGUAGE_CODE</command> where <literal>PATH_TO_SITE_CONFIG_FILE</literal> is the path to the <literal>homepage.cfg</literal> file in your local copy of the docs.fedoraproject.org website, and <literal>LANGUAGE_CODE</literal> is the language in which you are removing the document. Note that you can only run <command>publican remove_book</command> for one language at a time.
- </para>
- </listitem>
- <listitem>
- <para>
- Change to the directory in which you keep your local copy of the site and run:
- </para>
- <screen><command>git add .</command>
-<command>git commit -m "DESCRIPTION_OF_YOUR_CHANGES"</command>
-<command>git push</command></screen>
- </listitem>
- <listitem>
- <para>
- 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: <command>for f in $(git ls-files --deleted); do git rm $f; done </command>. Then push these changes to the remote repo: <command>git commit -m "rm unused files" git push</command>
- </para>
- <warning>
- <para>
- A <command>git rm</command> 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.
- </para>
- </warning>
- </listitem>
- </itemizedlist>
- </section>
- <section id="sect-publican-publishing-updating">
- <title>Updating a Document on the Web</title>
- <para>
- 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 <command>publican install_book</command>, as if you were installing it for the first time. Publican automatically replaces the old version with the new one.
- </para>
- </section>
- <section id="sect-publican-publishing-draft">
- <title>Marking a Documentation as Draft</title>
- <para>
- Release early, release often.
- </para>
- <para>
- Documents can be released before they are completely ready for the users. When this happens it's important to mark and publish the document as a draft. To do this there are three things that need to be done so that everyone knows that the guide isn't complete and ready for public consumption.
- </para>
- <para>
- The first is setting the draft switch in the document itself. To do this you need to add <command>status="draft"</command> to your <literal>Doc_Name.xml</literal> file in the <literal>book</literal> or <literal>article</literal> heading so it looks like <command>book status="draft"</command>. This provides a draft watermark on all pages of the text.
- </para>
- <para>
- The next task is to modify your <literal>Book_Info.xml</literal> or <literal>Article_Info.xml</literal> file. Change the <literal>productname</literal>tag to Fedora Draft Documentation and remove the contents of <literal>productnumber</literal>. Optionally, if you plan to release the document for a particular Fedora release, include the Fedora release number in the <literal>edition</literal> tag. For example, if you plan to release the book for Fedora 14, you would set edition to: <command>14.0.1</command>. Here 14.0.1 signifies Fedora 14, edition 0.1.
- </para>
- <para>
- Lastly, in the <literal>Publican.cfg</literal> add the following lines: <command>version: 0.1</command> and <command>web_version_label: UNUSED</command>.
- </para>
- <para>
- After completing the above tasks your guide will be sufficiently marked as draft and can safely be published to the Docs website.
- </para>
+ <title>Removing a Document</title>
+ <remark>Hic sunt leones...</remark>
</section>
</section>
<section id="sect-publican-packaging">
- <title>Building RPM Packages</title>
- <para>
- <remark>Hic sunt leones.</remark>
- </para>
+ <title>Packaging a Document</title>
+ <remark>Hic sunt leones.</remark>
</section>
</chapter>
More information about the docs-commits
mailing list