Plone-DocsBuilder

Docs for version 0.0.3

Install

Dependencies

  • Docker
  • A working Internet connection to pull the container on the first run
  • A index.rst file

Please follow the installation guide of Docker or consult the documentation of your Operating System to install Docker.

That is all !

You do not need to install anything else.

The first time you run plone-docsbuilder it will automatically pull the application container from Docker Hub.

In case you prefer to pull (download) the container yourself do the following:

docker pull testthedocs/plone-docsbuilder

This will download the latest version of the container.

If you for some reason want or need to use a certain version (release), you can do that too:

docker pull testthedocs/plone-docsbuilder:0.0.1

Please check the Changelog to find out more changes and releases.

Usage

Note

All commands in the documentation refrer to the installation according to the official ` Docker installation guide <https://docs.docker.com/engine/installation/>`_.

If you installed Docker via the package manager of your Operating System you may have to adjust the commands.

Meaning if you installed Docker on Ubuntu from the Ubuntu repositories the syntax would be docker.io in place of docker.

Download Image

Pull (download) plone-docsbuilder:

docker pull testthedocs/plone-docsbuilder

Update Image

Check and update application image to a newer version:

docker pull testthedocs/plone-docsbuilder

Building HTML

plone-docsbuilder is designed to build HTML out of rst files in your current working directory ($PWD).

The build output will be saved in a directory called _build in your $PWD.

Example

Change into your documentation dorectory (/docs) of your project:

cd docs

Do a ls to see all the files here:

index.rst

Run plone-docsbuilder:

docker run -v `pwd`:/build/docs testthedocs/plone-docsbuilder html

After the build is finished, check the content of the directory with ls again:

index.rst    _build

Roadmap

Collection of features which could be nice and may will be included.

There are not written nor will be (if) included in a particular order.

  • [ ] write logs to file
  • [ ] add quite mode (not showing cli output)
  • [ ] add log summary as nice colored output
  • [ ] add markdown (md) support
  • [ ] remove dependency on index.rst
  • [ ] remove dependency on _static
  • [ ] add option to use the default~ or the ‘official’ plone sphinx theme
  • [ ] add option to build docs which are not in $PWD
  • [ ] include sphinxcontrib-osexample

Releasing

This document explains the release process of plone-docsbuilder versions.

Overview

Development of plone-docsbuilder follows semantic versioning.

The master branch will always point to the most up to date development code.

For each release we have a own branch.

Workflow

  1. Clone the repository
git clone git@githublcom:testthedocs/plone-docsbuilder
  1. Create a branch, based on the master branch, for working in.
cd plone-docsbuilder
git checkout -b $COOL-AND-LOGICAL-NAME
  1. Work in this branch, create builds and test them and update the docs!
  2. Create a Pull Request against the master branch
  • Explain what you did
  • Why you did it
  1. Merge $BRANCH into master
  2. Create a release branch of the master
git checkout -b 0.0.4
  1. Update version in the VERSION file
  2. Update Changes.md
  3. Make a release
make release

Containerized application based on Sphinx for test builds of docs.plone.org.

The main purpose of this application is to create test builds in an ‘easy’, ‘fast’ and ‘repeatable’ way.

Note

plone-docsbuilder is not a full replacement of Sphinx, it is not meant to be !

It is meant for creating ‘test builds’ to get a visual impression not for more, no spell-check, no link-check and so on.

Limitations

  • plone-docsbuilder depends on an index.rst file in your root documentation directory, see our Roadmap for more info
  • plone-docsbuilder will report a warning, if there is no _static directory in your root documentation directory
  • sphinxcontrib-osexample is not included, yet