refs #147: base docs framework polishing (#171)

* refs #147: Access to Dockerized tools is now proxied by compose. * refs #147: Fixed a WIP make target. * refs #147: Changed folder structure to make docs more self-contained. * refs #147: Typo fix. * refs #147: Renamed container and target for consistency. * refs #147: Got rid of unnecessary nesting in folder structure. Relocated docs README file. * refs #147: Added working deploy target to makefile. The docs can be safely deployed to GH Pages. * refs #147: Added MkDocs metadata for site and github direct editing link. * refs #147: Deploy procedure now forcefully triggers API extraction. README file for docs updated.
carenalgas · Mar 11, 2024 · 6acb3fb · 6acb3fb
1 parent 85267ab
commit 6acb3fb
Show file tree

Hide file tree

Showing 132 changed files with 313 additions and 83 deletions.
diff --git a/.gitignore b/.gitignore
@@ -35,9 +35,12 @@ game
 game/**
 
 # Documentation ignores
-docs-src/**/*.import
-docs-src/**/scripting-reference/*.md
-!docs-src/**/scripting-reference/index.md
+docs/src/**/*.import
+docs/src/**/scripting-reference/*.md
+!docs/src/**/scripting-reference/index.md
+docs/dist/*
+docs/dist/**/*
+!docs/dist/.gitkeep
 Collector*.gd
 ReferenceCollectorCLI*.gd
-reference.json
+reference.json
diff --git a/Makefile b/Makefile
diff --git a/docker-compose.yml b/docker-compose.yml
diff --git a/docs-src/content/the-engine-handbook/scripting-reference/index.md b/docs-src/content/the-engine-handbook/scripting-reference/index.md
diff --git a/Dockerfile.DocsMaker → docs/Dockerfile.DocsExtractor b/Dockerfile.DocsMaker → docs/Dockerfile.DocsExtractor
@@ -37,7 +37,7 @@ RUN addgroup --system --gid ${DOCKER_USER_GID} ${DOCKER_USER} \
 
 WORKDIR /app
 
-COPY --chmod=777 generate_reference generate_reference
+COPY --chmod=777 scripts/generate_reference generate_reference
 
 # Install application dependencies
 RUN python3 setup.py install

diff --git a/Dockerfile.MkDocs → docs/Dockerfile.MkDocs b/Dockerfile.MkDocs → docs/Dockerfile.MkDocs
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,33 @@
+CURRENT_UID := $(shell id -u):$(shell id -g)
+
+all: docs-up
+
+docs-up:
+	docker compose pull
+	docker compose up -d --remove-orphans
+
+docs-down:
+	docker compose down
+
+docs-deploy: docs-extract
+	rm -rf ./dist && git restore dist
+	docker compose run \
+		--rm \
+		--user ${CURRENT_UID} \
+		documentation \
+		mkdocs build --verbose
+	GIT_DEPLOY_USERNAME="$(shell git config user.name)" GIT_DEPLOY_MAIL="$(shell git config user.email)" scripts/deploy_to_ghpages
+
+docs-extract:
+	docker compose run \
+		--rm \
+		--user $(CURRENT_UID) \
+		docs-extractor /project \
+		-o /output \
+		-d addons/popochiu/engine/
+
+cli:
+	docker compose run --rm documentation bash
+
+logs:
+	docker compose logs -f
diff --git a/docs-src/README.md → docs/README.md b/docs-src/README.md → docs/README.md
@@ -76,9 +76,9 @@ About Make, there are different ways to install it:
 
 ## Run the documentation
 
-To run the documentation, just enter the project's directory and issue this command:
+To run the documentation, just enter the `docs` directory in the project's repository and issue this command:
 
-> `make docs-up'
+> `make docs-up`
 
 This will start the Docker container, and will bind port 286 of the host to the running instance of MkDocs in the container. To view the docs live in your browser, just visit [http://localhost:286](http://localhost:286).
 
@@ -92,34 +92,39 @@ Please, read the contribution rules before pushing changes to Popochiu Documenta
 
 ## How to export scripting reference to the local development environment
 
-Scripting reference is automatically exported by GitHub Actions when the doc is published to production.  
-Should you want to export the refs locally to preview your work on the docs, a make command is available for that.
+Scripting reference ~~is~~ will be automatically exported by GitHub Actions when the doc is published to production.
 
-**IMPORTANT:** a preliminary step to export the scripting reference is to build the necessary docker image. For that, issue:
+> **NOTE**: At the time of writing, the documentation has to deployed manually to production. Please refer to the dedicated section below.
 
-> `make gdm-build`
+Exporting the Engine API refs is necessary to preview it locally. Also, the export procedure will be automatically triggered before every manual deploy to production. To extract the API refs without issuing a deploy, a make command has been made available.
 
-and wait for the build to end successfully. Once it's done you can issue:
+> `make docs-extract`
 
-> `make gdm-generate`
-
-to export all of the engine API docs to markdown format.  
+All of the engine API docs will be exported to markdown format.  
 The exported refereces will be available in `The Engine Handbook > Scripting Reference` section of the documentation.
 
-**NOTE**: There is no live-reload of the source code. If you change the docblocks in the engine's source files, you will have to manually export local refs again.
+**NOTE**: There is no live-reload from the plugin source code. If you change the docblocks in the engine's source files, you will have to manually export local refs again.
 
-**NOTE**: Locally generated exports are ignored by Git.
+**NOTE**: To avoid redundancy, exported API refs are ignored by Git, so only the documentation source files and the GDScript source files are versioned.
 
 ## How to publish the documentation to production
 
-MkDocs is automatically triggered by GitHub automation so that new versions of the documentation are published whit every new release.
+~~MkDocs is automatically triggered by GitHub Actions automation so that new versions of the documentation are published whit every new release.~~
+
+At the time of writing, the documentation has to be deployed manually to Github Pages. A make command is available for this task, that takes care of everything, that can be issued from every working branch (but will be usually be run from `develop`).
+
+> `make docs-deploy`
+
+> **NOTE**: This command requires writing permissions on Popochiu main repository, so it can be issued only by core project contributors.
+
+This command will create a local `gh-pages` branch. This branch can be thrown away, but the best option is to keep a local copy of it, because this will speed up subsequent update deploys.
 
-> TODO: create a live documentation site for dev branch too.
+> **NOTE**: The `gh-pages` branch contents will differ entirely from the other branches of the project. You should **NEVER** commit manually on the `gh-pages` branch, nor trying to merge it back to a source branch. It would be bad. Like... try to imagine all life as you know it stopping instantaneously and every molecule in your body exploding at the speed of light. Allright, that's bad.
 
 ## Additional information
 
 1. For those who make use of DNSDock or Dinghy Proxy, the documentation can be accessed visiting [http://docs.popochiu.local](docs.popochiu.local) on port `80`.
-2. You can do without GNU Make and use Docker Compose direcly, issueing:
+2. If you are really searching for trouble, and/or if you know what you're doing, you can do without GNU Make and use Docker Compose direcly, with:
     * `docker compose up -d` to run the service in background
     * `docker compose down` to stop the service
     * `docker compose up` to run the service and display logs in the console (`ctrl-c` will stop the service and send you back to the console)
diff --git a/...-src/content/the-engine-handbook/.gitkeep → docs/dist/.gitkeep b/...-src/content/the-engine-handbook/.gitkeep → docs/dist/.gitkeep
diff --git a/docs/docker-compose.yml b/docs/docker-compose.yml
@@ -0,0 +1,23 @@
+version: "3"
+services:
+    documentation:
+        ports:
+            - 286:80
+        volumes:
+            - .:/app
+        working_dir: /app
+        labels:
+            - com.dnsdock.alias=docs.popochiu.local
+        build:
+            context: .
+            dockerfile: Dockerfile.MkDocs
+        command: serve -a 0.0.0.0:80
+    docs-extractor:
+        volumes:
+            - ..:/project
+            - ./src/the-engine-handbook/scripting-reference:/output
+        profiles:
+            - tools
+        build:
+            context: .
+            dockerfile: Dockerfile.DocsExtractor
diff --git a/mkdocs.yml → docs/mkdocs.yml b/mkdocs.yml → docs/mkdocs.yml
@@ -1,5 +1,12 @@
-site_name: Popochiu
+site_name: Popochiu Documentation
+site_description: Home to the documentation of Popochiu, a Godot plugin to build point-and-click adventure games.
+site_author: The Carenalgas Community
+copyright: Copyright (c) 2024 - The Carenalgas Community
 repo_url: https://github.com/carenalgas/popochiu/
+edit_uri: edit/develop/docs/src/
+docs_dir: src
+site_dir: dist
+theme: readthedocs
 extra_css:
   - assets/css/custom.css
   - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/tomorrow-night-bright.min.css
@@ -18,6 +25,3 @@ markdown_extensions:
 plugins:
   - search
   - mkdocs-nav-weight
-theme: readthedocs
-docs_dir: docs-src/content
-site_dir: docs