site-author/content/xdocs/procedures/How_to_publish_docs.xml - forrest - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
 -->
 <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
   "http://forrest.apache.org/dtd/document-v20.dtd">
 <document>
   <header>
     <title>How to Publish Forrest Documentation</title>
     <abstract>
       This documents the steps to update the Forrest Website.
     </abstract>
   </header>
   <body>
     <section id="About">
       <title>Introduction</title>
       <p>
         All documentation about Apache Forrest is managed as a Forrest-built
         project located in the site-author directory of forrest/trunk SVN. The
         Apache Forrest website is updated by generating static pages from the
         site-author-project and committing them to the forrest/site SVN, which
         is then 'svn checkout' on the forrest.apache.org webserver to create the
         website.
       </p>
       <p>
         See other notes for the Documentation Coordination
         <a href="site:tasks">tasks</a>.
       </p>
     </section>
     <section id="forrestbot-local">
       <title>Updating the site with a local forrestbot</title>
       <p>
         Generating and publishing the main docs is very easy using a local
         forrestbot:
       </p>
       <source>cd site-author
 forrest -f publish.xml build
 forrest -f publish.xml deploy</source>
       <p>
         Note: if your system username is not the same as your "svn username"
         then provide a "deploy.svn.settings" file as explained at
         <code>$FORREST_HOME/etc/publishing_our_site.txt</code>
       </p>
       <p>
         This builds the documentation locally then deploys it by committing it
         to the
         <a href="http://svn.apache.org/repos/asf/forrest/site">forrest/site
         SVN</a>.
         The svnpubsub system automatically kicks in to do the final publish step.
       </p>
       <p>
         See more detailed <a href="site:forrestbot-svn">explanation</a> of this
         procedure.
       </p>
       <p>
         Publishing documentation for a particular plugin is done by:
       </p>
       <source>cd plugins/myPluginName
 $FORREST_HOME/tools/ant/bin/ant deploy-docs</source>
       <p>
         See further information in the
         <a href="site:buildPlugin">buildPlugin</a> doc.
       </p>
       <p>
         See some general notes about managing
         <a href="http://www.apache.org/dev/project-site.html">project
         websites</a>.
       </p>
     </section>
     <fixme author="open">
       This is work in progress.
     </fixme>
     <section id="OrgDoc">
       <title>Other docs</title>
       <p>
         There have been a few explantions of our docs processing on the
         forrest-dev mail list. Need to glean the info from them. Here is the
         content of some:
       </p>
       <source>
 <![CDATA[
                 To publish from trunk/site-author/

                 # Make changes to sources, and then test, then commit.

                 # Please, please, ensure valid xml docs. Errors will be
                 # reported during the 'build' phase if you don't.
                 # Also it prevents other people from working with the docs,
                 # which goes against the collaborative development process.

                 # You can do 'forrest validate-xdocs" beforehand or use
                 # a validating editor (link: catalog.html) or for a single doc use
                 # xmllint (link: catalog.html) from the command-line, e.g.
                 # xmllint --noout --valid --catalogs faq.xml

                 # Use the forrestbot to build and then deploy to svn.apache.org ...

                 cd site-author
                 forrest -f publish.xml build
                 # ... verify files in build/forrest-docs
                 forrest -f publish.xml deploy -Ddeploy.svn.commit-message="my commit message"

                 Now the files are in SVN at forrest/site
                 Periodically the real website files are updated from there.
                 You do not have to do anything else.

                 ----------------------
                 Note: The first time that you deploy, it will need to do
                 a long svn checkout first.
                  ]]>
       </source>
       <p>
         Some more notes that need to be integrated above ...
       </p>
       <p>
         Note that forrestbot does not remove docs from the forrest/site SVN
         (FOR-392). So need to manually delete:
         '<code>svn delete https://svn.apache.org/repos/asf/forrest/site/.../oldDoc</code>'
         and then remove it from the forrestbot work directories: 'cd
         $FORREST_HOME/site-author; rm build/forrest-docs/oldDoc; rm
         work/svn-deploy/forrest-docs/oldDoc'.
       </p>
       <p>
         The generated docs are in build/forrest-docs which is the name given to
         it in the forrestbot descriptor (site-author/publish.xml). Here is a
         trick for reviewing changes that forrestbot is ready to deploy ...
       </p>
       <source>
 forrest -f publish.xml build
 svn update work/svn-deploy/forrest-docs
 diff -rq work/svn-deploy/forrest-docs build/forrest-docs | grep -v "\.svn" | grep differ</source>
       <p>
         If you change something that affects all pages (e.g. layout changes; navigation
         menu additions or MOTD changes that affect old "versioned docs")
         then see the note in conf/cli.xconf about temporarily not excluding
         old "docs_*" patterns.
       </p>
       <p>
         If there have been changes to tools/forrestbar then need to follow the
         instructions there to build it. Then copy its build/forrestbar.xpi to
         site-author/content/xdocs/tools/forrestbar.xpi and commit that. Then run
         forrestbot to build and deploy the site, or alternatively for a quick
         fix, just commit it to forest/site/tools (which is what forrestbot would do).
       </p>
     </section>
   </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
	"http://forrest.apache.org/dtd/document-v20.dtd">
	<document>
	<header>
	<title>How to Publish Forrest Documentation</title>
	<abstract>
	This documents the steps to update the Forrest Website.
	</abstract>
	</header>
	<body>
	<section id="About">
	<title>Introduction</title>
	<p>
	All documentation about Apache Forrest is managed as a Forrest-built
	project located in the site-author directory of forrest/trunk SVN. The
	Apache Forrest website is updated by generating static pages from the
	site-author-project and committing them to the forrest/site SVN, which
	is then 'svn checkout' on the forrest.apache.org webserver to create the
	website.
	</p>
	<p>
	See other notes for the Documentation Coordination
	<a href="site:tasks">tasks</a>.
	</p>
	</section>
	<section id="forrestbot-local">
	<title>Updating the site with a local forrestbot</title>
	<p>
	Generating and publishing the main docs is very easy using a local
	forrestbot:
	</p>
	<source>cd site-author
	forrest -f publish.xml build
	forrest -f publish.xml deploy</source>
	<p>
	Note: if your system username is not the same as your "svn username"
	then provide a "deploy.svn.settings" file as explained at
	<code>$FORREST_HOME/etc/publishing_our_site.txt</code>
	</p>
	<p>
	This builds the documentation locally then deploys it by committing it
	to the
	<a href="http://svn.apache.org/repos/asf/forrest/site">forrest/site
	SVN</a>.
	The svnpubsub system automatically kicks in to do the final publish step.
	</p>
	<p>
	See more detailed <a href="site:forrestbot-svn">explanation</a> of this
	procedure.
	</p>
	<p>
	Publishing documentation for a particular plugin is done by:
	</p>
	<source>cd plugins/myPluginName
	$FORREST_HOME/tools/ant/bin/ant deploy-docs</source>
	<p>
	See further information in the
	<a href="site:buildPlugin">buildPlugin</a> doc.
	</p>
	<p>
	See some general notes about managing
	<a href="http://www.apache.org/dev/project-site.html">project
	websites</a>.
	</p>
	</section>
	<fixme author="open">
	This is work in progress.
	</fixme>
	<section id="OrgDoc">
	<title>Other docs</title>
	<p>
	There have been a few explantions of our docs processing on the
	forrest-dev mail list. Need to glean the info from them. Here is the
	content of some:
	</p>
	<source>
	<![CDATA[
	To publish from trunk/site-author/

	# Make changes to sources, and then test, then commit.

	# Please, please, ensure valid xml docs. Errors will be
	# reported during the 'build' phase if you don't.
	# Also it prevents other people from working with the docs,
	# which goes against the collaborative development process.

	# You can do 'forrest validate-xdocs" beforehand or use
	# a validating editor (link: catalog.html) or for a single doc use
	# xmllint (link: catalog.html) from the command-line, e.g.
	# xmllint --noout --valid --catalogs faq.xml

	# Use the forrestbot to build and then deploy to svn.apache.org ...

	cd site-author
	forrest -f publish.xml build
	# ... verify files in build/forrest-docs
	forrest -f publish.xml deploy -Ddeploy.svn.commit-message="my commit message"

	Now the files are in SVN at forrest/site
	Periodically the real website files are updated from there.
	You do not have to do anything else.

	----------------------
	Note: The first time that you deploy, it will need to do
	a long svn checkout first.
	]]>
	</source>
	<p>
	Some more notes that need to be integrated above ...
	</p>
	<p>
	Note that forrestbot does not remove docs from the forrest/site SVN
	(FOR-392). So need to manually delete:
	'<code>svn delete https://svn.apache.org/repos/asf/forrest/site/.../oldDoc</code>'
	and then remove it from the forrestbot work directories: 'cd
	$FORREST_HOME/site-author; rm build/forrest-docs/oldDoc; rm
	work/svn-deploy/forrest-docs/oldDoc'.
	</p>
	<p>
	The generated docs are in build/forrest-docs which is the name given to
	it in the forrestbot descriptor (site-author/publish.xml). Here is a
	trick for reviewing changes that forrestbot is ready to deploy ...
	</p>
	<source>
	forrest -f publish.xml build
	svn update work/svn-deploy/forrest-docs
	diff -rq work/svn-deploy/forrest-docs build/forrest-docs \| grep -v "\.svn" \| grep differ</source>
	<p>
	If you change something that affects all pages (e.g. layout changes; navigation
	menu additions or MOTD changes that affect old "versioned docs")
	then see the note in conf/cli.xconf about temporarily not excluding
	old "docs_*" patterns.
	</p>
	<p>
	If there have been changes to tools/forrestbar then need to follow the
	instructions there to build it. Then copy its build/forrestbar.xpi to
	site-author/content/xdocs/tools/forrestbar.xpi and commit that. Then run
	forrestbot to build and deploy the site, or alternatively for a quick
	fix, just commit it to forest/site/tools (which is what forrestbot would do).
	</p>
	</section>
	</body>
	</document>