README

------
docker
------
# Build the docker image with:
docker-compose build

# Run the image to build the docs with:
docker-compose run app

-----------------
Patch maintenance
-----------------
The document generation makes a few programmatic changes to the upstream
documentation in order to build successfully with SUSE theming, in the files
tox.ini, doc/requirements.txt, and doc/source/conf.gpy. Other changes to the
documentation are accomplished by maintaining patch files and applying them
during the build.  Whenever additional downstream modifications are necessary, a
new patch file needs to be created.  Use the following process to accomplish
this:

Generate the documentation, which applies the patch from this repo:
$ env PROJECTS={project} ./gen_docs.sh

Make and test document changes:
$ cd upstream/{project}

Iteratively:
 - Edit the document source under doc/source
 - Build the docs using:
       $ tox -e docs
 - View the built documents in a browser at:
       file:///...../doc-cloud/scripts/upstream/{project}/doc/build/html

When ready to generate the new patch file, first reset those files that the
script will programmatically modify:

$ git checkout tox.ini doc/requirements.txt doc/source/conf.py

Create the new patch file with
$ git diff > ../../patches/{projects}/00.patch

Commit it into git
$ cd ../..
$ git commit 

----------------------
Building upstream docs
----------------------

If you're required to build the upstream Administration and User Guides, you can build and
view each individual guide upstream: https://docs.openstack.org/doc-contrib-guide/docs-builds.html 

If you want to build the SUSE version, equivalent to what is published at at
suse.com/documentation, perform the following:

1. Clone this repository: https://github.com/SUSE-Cloud/doc-cloud-upstream
2. Change into the `/scripts/` directory:
   
   $ cd scripts
   
3. Run `./gen_docs.sh`

   This process clones every repository required, and builds them using
   the `suse_sphinx_theme`. You need to allocate at least an hour for the
   process to complete.
   
4. You can find the finished product in the `/scripts/build/` folder.

The completed `/build/` folder contains the full and complete content required
to publish to docserv or docserv2. Do not alter this format when publishing.