https://github.com/cakephp/docs-builder
A set of common tools to build documentation sites for plugins
https://github.com/cakephp/docs-builder
Last synced: 7 months ago
JSON representation
A set of common tools to build documentation sites for plugins
- Host: GitHub
- URL: https://github.com/cakephp/docs-builder
- Owner: cakephp
- Created: 2019-03-20T22:19:14.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2025-03-12T02:59:38.000Z (11 months ago)
- Last Synced: 2025-03-12T03:33:07.308Z (11 months ago)
- Language: PHP
- Homepage:
- Size: 113 KB
- Stars: 5
- Watchers: 14
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# CakePHP Plugin Docs Builder
This repository provides common tools for building documentation sites for
plugins maintained by the CakePHP team. This build tooling is *not meant* for
community plugins.
## Building docs with these tools
To use these tools your plugin should create a docker image based on
`markstory/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 site
using sphinx. An example of this is:
```dockerfile
# Generate the HTML output.
FROM markstory/cakephp-docs-builder as builder
COPY docs /data/docs
RUN 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-alpine
COPY --from=builder /data/website /data/website
COPY --from=builder /data/docs-builder/nginx.conf /etc/nginx/conf.d/default.conf
# Move each version into place
RUN 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'll
need at least the following:
* An `index.rst` that builds a `toctree` for all documents.
* A `conf.py` file that configures sphinx.
An example `conf.py` is as follows:
```python
# Global configuration information used across all the
# translations of documentation.
#
# Import the base theme configuration
from cakephpsphinx.config.all import *
# 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 bar
project = '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 built
version = '1.1'
# Language in use for this directory.
language = 'en'
```
## What these tools build
After defining a docker file for your plugin you and building the image, you'll
get 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.
## Adding a translation to a plugin's docs
The languages offered by a plugin are stored in a few places and each needs to
be updated separately:
* The `conf.py` file contains a `languages` list.
* Each translation needs to set `language` in its configuration file.
* The `docs.Dockerfile` in your plugin needs to pass `LANGS` to each make task
in `docs-builder` that is called.
* You need to update the jenkins deploy scripts in this repository to pass
`LANGS` when rebuilding elasticsearch indexes.
* Update build jobs in jenkins.
# Pushing update of this project's docker image
When you make changes to either cakephp/cakephpsphinx or this repository you
need to publish a new docker image and update the cakephp server.
1. Go to the [project actions](https://github.com/cakephp/docs-builder/actions)
2. Run the `Build and publish images` workflow.
This will build new images and publish them to ghcr.io. Once new images
have been published they need to be pulled onto the cakephp.org server
```bash
ssh apps.cakephp.org
docker pull ghcr.io/cakephp/docs-builder
docker pull ghcr.io/cakephp/docs-builder:runtime
```