- Notifications
You must be signed in to change notification settings - Fork4
cakephp/docs-builder
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
This repository provides common tools for building documentation sites forplugins maintained by the CakePHP team. This build tooling isnot meant forcommunity plugins.
To use these tools your plugin should create a docker image based onmarkstory/cakephp-docs-builder. It should add your plugin's docs to/data/docs and then use the tools provided in the base image to build the siteusing sphinx. An example of this is:
# Generate the HTML output.FROM markstory/cakephp-docs-builder as builderCOPY docs /data/docsRUN cd /data/docs-builder && \# In the future repeat website for each version make website SOURCE=/data/docs DEST=/data/website/1.1# Build a small nginx container with just the static site in it.FROM nginx:1.15-alpineCOPY --from=builder /data/website /data/websiteCOPY --from=builder /data/docs-builder/nginx.conf /etc/nginx/conf.d/default.conf# Move each version into placeRUN mv /data/website/1.1/html/ /usr/share/nginx/html/1.1
Your plugin's docs will need to define a minimal sphinx configuration. You'llneed at least the following:
- An
index.rstthat builds atoctreefor all documents. - A
conf.pyfile that configures sphinx.
An exampleconf.py is as follows:
# Global configuration information used across all the# translations of documentation.## Import the base theme configurationfromcakephpsphinx.config.allimport*# The version info for the project you're documenting, acts as replacement for# |version| and |release|, also used in various other places throughout the# built documents.## The full version, including alpha/beta/rc tags.release='1.1'# The search index version. This needs to match# the INDEX_PREFIX variable used when `make populate-index` is called.search_version='authorization-11'# The marketing display name for the book.version_name=''# Project name shown in the black header barproject='CakePHP Authorization'# Other versions that display in the version picker menu.version_list= [ {'name':'1.1','number':'1.1','title':'1.1.x','current':True},]# Languages available.languages= ['en']# The GitHub branch name for this version of the docs# for edit links to point at.branch='master'# Current version being builtversion='1.1'# Language in use for this directory.language='en'
After defining a docker file for your plugin you and building the image, you'llget the following:
- A static HTML site built with sphinx, using the cakephp-sphinxtheme
- Nginx serving out of
/var/www/html. - Dokku configuration for re-indexing content after the app starts up.
The languages offered by a plugin are stored in a few places and each needs tobe updated separately:
- The
conf.pyfile contains alanguageslist. - Each translation needs to set
languagein its configuration file. - The
docs.Dockerfilein your plugin needs to passLANGSto each make taskindocs-builderthat is called. - You need to update the jenkins deploy scripts in this repository to pass
LANGSwhen rebuilding elasticsearch indexes. - Update build jobs in jenkins.
When you make changes to either cakephp/cakephpsphinx or this repository youneed to publish a new docker image and update the cakephp server.
- Go to theproject actions
- Run the
Build and publish imagesworkflow.
This will build new images and publish them to ghcr.io. Once new imageshave been published they need to be pulled onto the cakephp.org server
ssh apps.cakephp.orgdocker pull ghcr.io/cakephp/docs-builderdocker pull ghcr.io/cakephp/docs-builder:runtime
About
A set of common tools to build documentation sites for plugins