{"id":29017852,"url":"https://github.com/cakephp/docs-builder","last_synced_at":"2025-06-25T23:07:16.260Z","repository":{"id":43021264,"uuid":"176825770","full_name":"cakephp/docs-builder","owner":"cakephp","description":"A set of common tools to build documentation sites for plugins","archived":false,"fork":false,"pushed_at":"2025-03-12T02:59:38.000Z","size":116,"stargazers_count":5,"open_issues_count":0,"forks_count":4,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-03-12T03:33:07.308Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cakephp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-20T22:19:14.000Z","updated_at":"2025-03-12T02:59:41.000Z","dependencies_parsed_at":"2024-11-03T18:17:37.171Z","dependency_job_id":"e00833b6-9b63-41be-9acf-1510a6b2b11c","html_url":"https://github.com/cakephp/docs-builder","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cakephp/docs-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cakephp%2Fdocs-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cakephp%2Fdocs-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cakephp%2Fdocs-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cakephp%2Fdocs-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cakephp","download_url":"https://codeload.github.com/cakephp/docs-builder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cakephp%2Fdocs-builder/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261967132,"owners_count":23237663,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-25T23:07:15.478Z","updated_at":"2025-06-25T23:07:16.252Z","avatar_url":"https://github.com/cakephp.png","language":"PHP","readme":"# CakePHP Plugin Docs Builder\n\nThis repository provides common tools for building documentation sites for\nplugins maintained by the CakePHP team. This build tooling is *not meant* for\ncommunity plugins.\n\n\n## Building docs with these tools\n\nTo use these tools your plugin should create a docker image based on\n`markstory/cakephp-docs-builder`. It should add your plugin's docs to\n`/data/docs` and then use the tools provided in the base image to build the site\nusing sphinx. An example of this is:\n\n```dockerfile\n# Generate the HTML output.\nFROM markstory/cakephp-docs-builder as builder\n\nCOPY docs /data/docs\n\nRUN cd /data/docs-builder \u0026\u0026 \\\n  # In the future repeat website for each version\n  make website SOURCE=/data/docs DEST=/data/website/1.1\n\n\n# Build a small nginx container with just the static site in it.\nFROM nginx:1.15-alpine\n\nCOPY --from=builder /data/website /data/website\nCOPY --from=builder /data/docs-builder/nginx.conf /etc/nginx/conf.d/default.conf\n\n# Move each version into place\nRUN mv /data/website/1.1/html/ /usr/share/nginx/html/1.1\n```\n\nYour plugin's docs will need to define a minimal sphinx configuration. You'll\nneed at least the following:\n\n* An `index.rst` that builds a `toctree` for all documents.\n* A `conf.py` file that configures sphinx.\n\nAn example `conf.py` is as follows:\n\n```python\n# Global configuration information used across all the\n# translations of documentation.\n#\n# Import the base theme configuration\nfrom cakephpsphinx.config.all import *\n\n# The version info for the project you're documenting, acts as replacement for\n# |version| and |release|, also used in various other places throughout the\n# built documents.\n#\n\n# The full version, including alpha/beta/rc tags.\nrelease = '1.1'\n\n# The search index version. This needs to match\n# the INDEX_PREFIX variable used when `make populate-index` is called.\nsearch_version = 'authorization-11'\n\n# The marketing display name for the book.\nversion_name = ''\n\n# Project name shown in the black header bar\nproject = 'CakePHP Authorization'\n\n# Other versions that display in the version picker menu.\nversion_list = [\n    {'name': '1.1', 'number': '1.1', 'title': '1.1.x', 'current': True},\n]\n\n# Languages available.\nlanguages = ['en']\n\n# The GitHub branch name for this version of the docs\n# for edit links to point at.\nbranch = 'master'\n\n# Current version being built\nversion = '1.1'\n\n# Language in use for this directory.\nlanguage = 'en'\n```\n\n## What these tools build\n\nAfter defining a docker file for your plugin you and building the image, you'll\nget the following:\n\n* A static HTML site built with sphinx, using the cakephp-sphinxtheme\n* Nginx serving out of `/var/www/html`.\n* Dokku configuration for re-indexing content after the app starts up.\n\n## Adding a translation to a plugin's docs\n\nThe languages offered by a plugin are stored in a few places and each needs to\nbe updated separately:\n\n* The `conf.py` file contains a `languages` list.\n* Each translation needs to set `language` in its configuration file.\n* The `docs.Dockerfile` in your plugin needs to pass `LANGS` to each make task\n  in `docs-builder` that is called.\n* You need to update the jenkins deploy scripts in this repository to pass\n  `LANGS` when rebuilding elasticsearch indexes.\n* Update build jobs in jenkins.\n\n\n# Pushing update of this project's docker image\n\nWhen you make changes to either cakephp/cakephpsphinx or this repository you\nneed to publish a new docker image and update the cakephp server.\n\n1. Go to the [project actions](https://github.com/cakephp/docs-builder/actions)\n2. Run the `Build and publish images` workflow.\n\nThis will build new images and publish them to ghcr.io. Once new images\nhave been published they need to be pulled onto the cakephp.org server\n\n```bash\nssh apps.cakephp.org\ndocker pull ghcr.io/cakephp/docs-builder\ndocker pull ghcr.io/cakephp/docs-builder:runtime\n```\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcakephp%2Fdocs-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcakephp%2Fdocs-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcakephp%2Fdocs-builder/lists"}