mirror of
https://github.com/owncloud/ocis
synced 2026-04-25 17:25:21 +02:00
fix docs build process
This commit is contained in:
Martin Mattel
1
docs/.gitignore
vendored
1
docs/.gitignore
vendored
@@ -1,5 +1,4 @@
|
||||
hugo/
|
||||
grpc_apis/
|
||||
mutagen.yml.lock
|
||||
helpers/output/*
|
||||
services/**/_index.md
|
||||
|
||||
123
docs/Makefile
123
docs/Makefile
@@ -1,55 +1,96 @@
|
||||
SHELL := bash
|
||||
# we need an override so that this variable is cleanly set in this makefile
|
||||
# else it might come from somewhere else
|
||||
override HUGO := $(CURDIR)/hugo
|
||||
override HDIR := $(HUGO)/.git
|
||||
|
||||
include ../.bingo/Variables.mk
|
||||
# if the directory exists, print that we do not need to prepare
|
||||
hugo-exists:
|
||||
@if [ -d $(HDIR) ]; then \
|
||||
echo; \
|
||||
echo 'Build environment for hugo exists, nothing to setup, continuing.'; \
|
||||
fi
|
||||
|
||||
# if the directory does not extist, initialize the framework and create the theme
|
||||
$(HDIR):
|
||||
@echo 'Initialize the hugo framework and build the theme, no docs get built.'
|
||||
@mkdir -p $(HUGO)/content/
|
||||
@mkdir -p $(HUGO)/extensions/
|
||||
@mkdir -p $(HUGO)/public/
|
||||
@cd $(HUGO) && git init
|
||||
@cd $(HUGO) && git config advice.detachedHead false
|
||||
@cd $(HUGO) && git remote rm origin || true
|
||||
@cd $(HUGO) && git remote add origin https://github.com/owncloud/owncloud.github.io
|
||||
@cd $(HUGO) && git fetch --depth=1
|
||||
@cd $(HUGO) && git checkout origin/main -f
|
||||
@$(MAKE) -C $(HUGO) --no-print-directory theme
|
||||
|
||||
# print available make targets
|
||||
.PHONY: help
|
||||
.DEFAULT_GOAL := help
|
||||
help:
|
||||
@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk -F'[:;##]' '{printf "\033[36m%-30s\033[0m %s\n", $$2, $$NF}'
|
||||
@echo -e 'Available .PHONY targets: \n'
|
||||
@grep -P -o '(?<=^\.PHONY: )(.*)' Makefile | sort -u
|
||||
@echo
|
||||
|
||||
.PHONY: docs-generate
|
||||
docs-generate: ## run docs-generate for all oCIS services
|
||||
# alternative target because we also use it in the root's makefile
|
||||
.PHONY:list
|
||||
list: help
|
||||
|
||||
# for drone only. drone uses an image for hugo that needs the hugo folder in the root
|
||||
# CURDIR will work for make only but not when running manually in the shell
|
||||
.PHONY: docs-hugo-drone-prep
|
||||
docs-hugo-drone-prep:
|
||||
@echo
|
||||
@echo 'Linking directory hugo for drone.'
|
||||
@rm -f ../hugo
|
||||
@ln -s $(HUGO) ../hugo
|
||||
|
||||
# generate data from sources such as services
|
||||
.PHONY: docs-run-helpers
|
||||
docs-run-helpers:
|
||||
@echo
|
||||
@echo 'Generate envvar adoc and md tables for all oCIS services used for dev and admin docs'
|
||||
@pushd helpers && go run .; popd
|
||||
|
||||
# create the docs build environment
|
||||
.PHONY: docs-init
|
||||
docs-init:
|
||||
@mkdir -p hugo/content/
|
||||
@mkdir -p hugo/public/
|
||||
@touch hugo/public/.nojekyll
|
||||
@cd hugo && git init
|
||||
@cd hugo && git config advice.detachedHead false
|
||||
@cd hugo && git remote rm origin || true
|
||||
@cd hugo && git remote add origin https://github.com/owncloud/owncloud.github.io
|
||||
@cd hugo && git fetch --depth=1
|
||||
@cd hugo && git checkout origin/main -f
|
||||
@$(MAKE) -C hugo theme
|
||||
docs-init: hugo-exists $(HDIR)
|
||||
# if there is nothing to do, stop printing that
|
||||
# another way would be https://stackoverflow.com/questions/58039810/makefiles-what-is-an-order-only-prerequisite
|
||||
@:
|
||||
|
||||
# the docs-build|serve commands require that docs-init was run first for the required data to exists
|
||||
# create a docs build
|
||||
.PHONY: docs-build
|
||||
docs-build:
|
||||
@echo
|
||||
@echo 'Building ocis for owncloud.dev'
|
||||
@$(MAKE) -C $(HUGO) --no-print-directory hugo-build
|
||||
@echo 'To view the rendered docs in the browser, run: make docs-serve'
|
||||
|
||||
# serve built docs with hugo
|
||||
.PHONY: docs-serve
|
||||
docs-serve: docs-init docs-generate docs-copy ## serve docs with hugo
|
||||
@bash -c "trap 'trap - SIGINT SIGTERM ERR; $(MAKE) --no-print-directory docs-sync-stop; exit 0' SIGINT SIGTERM ERR; $(MAKE) --no-print-directory docs-sync-start && $(MAKE) --no-print-directory hugo-serve"
|
||||
|
||||
.PHONY: test
|
||||
test: $(HUGO)
|
||||
@cd hugo && $(HUGO)
|
||||
|
||||
.PHONY: hugo-serve
|
||||
hugo-serve: $(HUGO)
|
||||
@cd hugo && $(HUGO) server
|
||||
docs-serve:
|
||||
@$(MAKE) -C $(HUGO) --no-print-directory hugo-server
|
||||
|
||||
# copy required resources into hugo
|
||||
.PHONY: docs-copy
|
||||
docs-copy: docs-init docs-sync-start docs-sync-stop
|
||||
docs-copy:
|
||||
@echo
|
||||
@echo 'Syncing required doc files and directories for the build process.'
|
||||
# brace expansion not with sh
|
||||
@rsync --delete -ax --exclude={hugo,templates,Makefile,.gitignore,README.md} ./ $(HUGO)/content/
|
||||
|
||||
.PHONY: docs-sync-start
|
||||
docs-sync-start: $(MUTAGEN)
|
||||
@$(MUTAGEN) project terminate || true
|
||||
@$(MUTAGEN) daemon stop || true
|
||||
@$(MUTAGEN) project start
|
||||
@$(MUTAGEN) project flush
|
||||
|
||||
.PHONY: docs-sync-stop
|
||||
docs-sync-stop: $(MUTAGEN)
|
||||
@$(MUTAGEN) project terminate
|
||||
@$(MUTAGEN) daemon stop
|
||||
|
||||
.PHONY: clean
|
||||
clean: ## clean up docs build artifacts
|
||||
@rm -rf hugo
|
||||
# clean up docs build artifacts (removing the hugo folder)
|
||||
.PHONY: docs-clean
|
||||
docs-clean:
|
||||
# NOTE: the whitespace at the beginning of the ifeq/else/endif statements is intentional.
|
||||
@echo
|
||||
ifneq ($(shell id -u), 0)
|
||||
@echo "You must run the clean command using sudo or as root because some doc files are created by root"
|
||||
else
|
||||
@echo 'Clean up docs build artifacts'
|
||||
@rm -rf $(HUGO)
|
||||
@echo "Removed folder: $(HUGO)"
|
||||
endif
|
||||
|
||||
@@ -1,14 +0,0 @@
|
||||
sync:
|
||||
docs:
|
||||
mode: one-way-replica
|
||||
alpha: .
|
||||
beta: ./hugo/content
|
||||
flushOnCreate: true
|
||||
ignore:
|
||||
paths:
|
||||
- .gitignore
|
||||
- mutagen.yml
|
||||
- mutagen.yml.lock
|
||||
- hugo
|
||||
- README.md
|
||||
- Makefile
|
||||
@@ -15,11 +15,20 @@ The documentation:
|
||||
|
||||
* Is based on the [HUGO](https://gohugo.io/) framework written in Go. The underlaying language is markdown plus the extensions provided by hugo.
|
||||
* The framwork including the theme used is maintained in the following [repo](https://github.com/owncloud/owncloud.github.io).
|
||||
* The hugo version, currently at `0.129.0` must be equal on both the ocis repo (`cat .bingo/Variables.mk | grep HUGO`) and in the framework repo (defined in `.drone.yml`).\
|
||||
* The hugo version, currently at `0.129.0` must match the image version defined in the root makefile and the framework repo, defined in `.drone.yml`.\
|
||||
{{< hint info >}}
|
||||
Any intended upgrade of the hugo version implies a check if the theme builds correctly and must be applied to all doc sourcing repos. On errors, stick on the current hugo version or update the theme accordingly!
|
||||
* Building the theme is part of the loaded framework while building the documentation is done using a separate container.
|
||||
|
||||
* Any intended upgrade of the hugo version implies a check if the theme builds correctly and must be applied to all doc sourcing repos. On errors, stick on the current hugo version or update the theme accordingly!
|
||||
{{< /hint >}}
|
||||
|
||||
* The documentation sources are distributed over several repos such as `ocis`, `web` and others. When building, these sources act individually and only those sources are build and pushed to the web that come from the respective repo. The definition what is going where is defined in the [framework repo](https://github.com/owncloud/owncloud.github.io/blob/main/.batchfile). This means, each merge of a docs change in one of the sourcing repos only pushes that change to the site. There is no global build process and inter doc links must be treated therefore very carefully !
|
||||
|
||||
* The documentation setup is, with only a few exceptions, identical for both the `ocis` and the `web` repo. This means, for example, running commands locally are the same, the documentation process section below applies for both; only drone uses some specifics.
|
||||
|
||||
* {{< hint info >}}
|
||||
Any files or folders that need to be excluded from the build process must be defined in the referenced framework repository above, in the file `config.yaml`.
|
||||
{{< /hint >}}
|
||||
* The documentation sources are distributed over several repos such as `ocis`, `web` and others. When building, these sources act individually and only those sources are build and pushed to the web that come from the respective repo. The definition what is going where is defined in the [framework repo](https://github.com/owncloud/owncloud.github.io/blob/main/.batchfile). This means, each merge of a docs change in one of the sourcing repos only pushes that change to the site. There is no global build process and inter doc links must be treated very carefully !
|
||||
|
||||
## Documentation Process
|
||||
|
||||
@@ -37,15 +46,33 @@ When a docs PR gets merged, the content of the `docs/` folder gets "copied". For
|
||||
## Building the Documentation
|
||||
|
||||
{{< hint info >}}
|
||||
* For building the documentation you need to have `make` and `go` installed. See the [ocis README](https://github.com/owncloud/ocis/#use-the-ocis-repo-as-source) for more details and minimum versions required.
|
||||
* For building the documentation locally, you need to have `make`, `docker` and `go` installed.\
|
||||
See the [ocis README](https://github.com/owncloud/ocis/#use-the-ocis-repo-as-source) for more details and minimum versions required.
|
||||
* Regulary, at least once after cloning, branching or rebasing, run `make generate` to update the assets. This ensures that all data that is accessed by the docs build process is up-to-date.
|
||||
* Run the make commands from the ocis root, the makefile contains all required targets.\
|
||||
Use `make help` for more details.
|
||||
{{< /hint >}}
|
||||
|
||||
* **To view the documentation locally** or after fixing typos only, without adding new content such as links or new documents, just run `make -C docs docs-serve` from within the root level of the oCIS git repository. This will make the documentation available on [localhost:1313](http://localhost:1313) and also do a hot reload if you change something in the (non autogenerated) documentation files.
|
||||
* **For any changes**, you must fully build the documentation first to preview it.\
|
||||
For ease of working, open two terminals and change to the ocis root. The terminals are numberd as (1) and (2).
|
||||
* At first start, from any terminal, run `sudo make docs-clean` to have a clean build environment.\
|
||||
sudo is required for deletion, because files generated by hugo, which runs in a container, are created by root.
|
||||
* Do all the doc changes required in the docs repository.
|
||||
* Run (1) `make docs-local`. This will run all steps locally as drone would do but without branch copying or pushing to the web. When omitting this step and just serving content, the documentation might build locally but may fail when creating a PR.
|
||||
* Run (2) `make docs-serve` to serve the documentation. You can now view the built result in the browser.
|
||||
* On any more changes made, run (1) `make docs-copy`. The changes will be built on the fly via the running docs-serve command.
|
||||
|
||||
* **When doing more changes than fixing typos**, you need to fully build the documentation running `make docs-drone-test`. This will run all steps locally as drone would do but without branch copying or pushing to the web. When omitting this step and just serving content, the documentation might build locally but may fail when creating a PR. Use the command described above to serve docs for a browser preview.
|
||||
* **To preview the documentation locally** without changing content, run the following commands in order.\
|
||||
This builds the documentation without artifacts and makes it available on [localhost:1313](http://localhost:1313).
|
||||
* `sudo make docs-clean`
|
||||
* `make docs-local`
|
||||
* `make docs-serve`
|
||||
|
||||
Note that you may get files changed reported like `env_vars.yaml` by just running the make command. You can discard any of these as they come from an internal helper process step necessary. To take care on those changed files, see the [Environment Variables]({{< ref "../services/general-info/envvars/" >}}) documentation.
|
||||
## Remarks
|
||||
|
||||
{{< hint info >}}
|
||||
Note that you may get files changed reported like `env_vars.yaml` by just running the make docs commands. You can discard any of these as they come from an internal helper process step necessary. To take care on those changed files, see the [Environment Variables]({{< ref "../services/general-info/envvars/" >}}) documentation.
|
||||
{{< /hint >}}
|
||||
|
||||
Please keep this documentation in sync with the oCIS source code of the master branch.
|
||||
|
||||
|
||||
@@ -20,11 +20,13 @@ Ask the developers if envvars of this type have been changed (added or removed).
|
||||
|
||||
## Extended Envvars
|
||||
|
||||
* Run from the ocis root `make -C docs docs-generate`\
|
||||
* From the ocis root run:\
|
||||
`sudo make docs-clean`\
|
||||
`make docs-generate`\
|
||||
Drop any changes in `env_vars.yaml`!
|
||||
* Check if there is a change in the `extended-envars.yaml` output.\
|
||||
If so, process [Extended Envvars - Fixing Changed Item]({{< ref "./special-envvars.md#fixing-changed-items" >}}).
|
||||
* When done, re-run the make command and check if the output of `./docs/services/_includes/adoc/extended_configvars.adoc` matches the expectations.
|
||||
* When done, re-run `make docs-generate` and check if the output matches the expectations in `./docs/services/_includes/adoc/extended_configvars.adoc`.
|
||||
|
||||
## Ordinary Envvars
|
||||
|
||||
@@ -32,15 +34,17 @@ If so, process [Extended Envvars - Fixing Changed Item]({{< ref "./special-envva
|
||||
|
||||
This is **mandatory for a new release** !
|
||||
|
||||
* Run from the ocis root `make -C docs docs-generate`\
|
||||
* From the ocis root run:\
|
||||
`sudo make docs-clean`\
|
||||
`make docs-generate`\
|
||||
Any changes in `env_vars.yaml` are now considered.
|
||||
* This file will most likely show changes and merging them is essential as **base for added/removed or deprecated envvars**. Note that this file will get additions/updates only, but items never get deleted automatically !!\
|
||||
* This file will most likely show changes and merging them is **essential** as base for **added/removed or deprecated envvars**. Note that this file will get additions/updates only, but items never get deleted automatically !!\
|
||||
{{< hint info >}}
|
||||
Note that due to how the code is currently designed, **things may get shifted** around though no real changes have been introduced.
|
||||
{{< /hint >}}
|
||||
* First, check if any **alphabetic code names** are present in the changes. See [Introduce new Envvars]({{< ref "./envvar-naming-scopes.md/#introduce-new-envvars" >}}).
|
||||
* If so, create a new branch and replace them in the **service containing the source** with the actual semantic version (e.g. `releaseX` → `7.2.0`) first. Note that ALL of major, minor and patch numbers must be present, including patch versions == `0`.
|
||||
* If all changes are applied, rerun `make -C docs docs-generate` and check if all changes are incorporated in the yaml file.
|
||||
* If all changes are applied, rerun `make docs-generate` and check if all changes are incorporated in the yaml file.
|
||||
* Create a PR and merge these changes, dont forget to do a local pull of master afterwards...
|
||||
* With a new branch, remove all envvars from the `env_vars.yaml` file manually that have formerly been deprecated and removed from the code.
|
||||
* Commit the changes and merge it.\
|
||||
|
||||
Reference in New Issue
Block a user