mirror of
https://github.com/cytopia/devilbox.git
synced 2024-12-19 21:07:53 +00:00
Build documentation in CI
This commit is contained in:
cytopia
parent
bdf8eb7578
commit
921188a5b3
54
.github/workflows/documentation.yml
vendored
Normal file
54
.github/workflows/documentation.yml
vendored
Normal file
@ -0,0 +1,54 @@
|
||||
---
|
||||
|
||||
# -------------------------------------------------------------------------------------------------
|
||||
# Job Name
|
||||
# -------------------------------------------------------------------------------------------------
|
||||
name: Docs
|
||||
|
||||
|
||||
# -------------------------------------------------------------------------------------------------
|
||||
# When to run
|
||||
# -------------------------------------------------------------------------------------------------
|
||||
on:
|
||||
# Runs on Pull Requests
|
||||
pull_request:
|
||||
|
||||
# Runs on master Branch and Tags
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
tags:
|
||||
|
||||
|
||||
# -------------------------------------------------------------------------------------------------
|
||||
# What to run
|
||||
# -------------------------------------------------------------------------------------------------
|
||||
jobs:
|
||||
docs:
|
||||
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
target:
|
||||
- build
|
||||
- linkcheck
|
||||
- linkcheck2
|
||||
|
||||
name: "[Docs ${{ matrix.target }}]"
|
||||
steps:
|
||||
|
||||
# ------------------------------------------------------------
|
||||
# Checkout repository
|
||||
# ------------------------------------------------------------
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v1
|
||||
|
||||
- name: Check documentation
|
||||
shell: bash
|
||||
run: |
|
||||
cd docs
|
||||
make ${TARGET}
|
||||
env:
|
||||
TARGET: ${{ matrix.target }}
|
||||
1
.gitignore
vendored
1
.gitignore
vendored
@ -121,6 +121,7 @@
|
||||
/docs/_build/
|
||||
/docs/make.bat
|
||||
/docs/linkcheck
|
||||
/docs/venv
|
||||
*.rst.todo
|
||||
|
||||
# Ignore vhost-gen files in test dir (copied on the fly)
|
||||
|
||||
123
.travis.yml
123
.travis.yml
@ -30,7 +30,9 @@ env:
|
||||
###
|
||||
### Check Documentation
|
||||
###
|
||||
- S1=DOCUMENTATION
|
||||
- S1=DOCUMENTATION V1=Build
|
||||
- S1=DOCUMENTATION V1=linkcheck
|
||||
- S1=DOCUMENTATION V1=linkcheck2
|
||||
|
||||
###
|
||||
### Check Update script
|
||||
@ -222,6 +224,11 @@ env:
|
||||
- S1=PHP V1=7.2 S2=MONGO V2=4.2
|
||||
|
||||
|
||||
jobs:
|
||||
allow_failures:
|
||||
- env: S1=DOCUMENTATION V1=linkcheck2
|
||||
|
||||
|
||||
###
|
||||
### Installation
|
||||
###
|
||||
@ -231,14 +238,6 @@ install:
|
||||
until sudo apt-get update -qq; do sleep 5; done
|
||||
fi
|
||||
|
||||
# Install dependencies for documentation
|
||||
- if [ "${S1}" = "DOCUMENTATION" ]; then
|
||||
until pip install sphinx; do sleep 5; done;
|
||||
until pip install sphinx-autobuild; do sleep 5; done;
|
||||
until pip install recommonmark; do sleep 5; done;
|
||||
until pip install sphinx_rtd_theme; do sleep 5; done;
|
||||
fi
|
||||
|
||||
# Determine latest Docker version in apt
|
||||
- DOCKER_APT="";
|
||||
if [ "${S1}" = "DOCKER" ]; then
|
||||
@ -265,6 +264,18 @@ install:
|
||||
sudo mv -f docker-compose /usr/local/bin;
|
||||
fi
|
||||
|
||||
# Provide retry function
|
||||
- retry() {
|
||||
for ((n=0; n<60; n++)); do
|
||||
echo "[${n}] ${*}";
|
||||
if eval "${*}"; then
|
||||
return 0;
|
||||
fi;
|
||||
sleep 1;
|
||||
done;
|
||||
return 1;
|
||||
}
|
||||
|
||||
|
||||
###
|
||||
### Before Script
|
||||
@ -283,13 +294,6 @@ before_script:
|
||||
- sudo service docker stop || true
|
||||
- sudo service docker start || true
|
||||
|
||||
# Show Python/pip
|
||||
- if [ "${S1}" = "DOCUMENTATION" ]; then
|
||||
pip freeze;
|
||||
pip --version;
|
||||
python --version;
|
||||
fi
|
||||
|
||||
# Show Docker/Docker Compose
|
||||
- if [ "${S1}" != "DOCUMENTATION" ]; then
|
||||
docker --version;
|
||||
@ -301,34 +305,65 @@ before_script:
|
||||
### Test
|
||||
###
|
||||
script:
|
||||
|
||||
###
|
||||
### Test Modules
|
||||
###
|
||||
- if [ "${S1}" = "MODULES" ]; then
|
||||
cd .tests/;
|
||||
make update-readme;
|
||||
git diff --quiet || { echo "Build Changes"; git diff; git status; false; }
|
||||
elif [ "${S1}" = "DOCUMENTATION" ]; then
|
||||
cd docs/;
|
||||
make build;
|
||||
make linkcheck;
|
||||
make linkcheck2;
|
||||
elif [ "${S1}" = "UPDATE" ]; then
|
||||
./update-docker.sh "${V1}";
|
||||
else
|
||||
cd .tests/;
|
||||
if [ "${S1}" != "DOCKER" ]; then
|
||||
make configure KEY="${S1}_SERVER" VAL="${V1}";
|
||||
make configure KEY="${S2}_SERVER" VAL="${V2}";
|
||||
fi;
|
||||
make start;
|
||||
make test-smoke-modules;
|
||||
make test-smoke-config;
|
||||
make test-smoke-intranet;
|
||||
make test-smoke-vendors;
|
||||
make test-smoke-vhosts;
|
||||
make test-smoke-rproxies;
|
||||
make test-smoke-ssl;
|
||||
make test-smoke-bind;
|
||||
make test-smoke-autostart;
|
||||
make test-smoke-framework-cakephp;
|
||||
make test-smoke-framework-drupal;
|
||||
make test-smoke-framework-wordpress;
|
||||
retry make update-readme;
|
||||
fi
|
||||
- if [ "${S1}" = "MODULES" ]; then
|
||||
git diff --quiet || { echo "Build Changes"; git diff; git status; false; };
|
||||
fi
|
||||
|
||||
###
|
||||
### Test Documentation
|
||||
###
|
||||
- if [ "${S1}" = "DOCUMENTATION" ] && [ "${V1}" = "Build" ]; then
|
||||
cd docs/;
|
||||
retry make build;
|
||||
fi
|
||||
- if [ "${S1}" = "DOCUMENTATION" ] && [ "${V1}" = "linkcheck" ]; then
|
||||
cd docs/;
|
||||
retry make linkcheck;
|
||||
fi
|
||||
- if [ "${S1}" = "DOCUMENTATION" ] && [ "${V1}" = "linkcheck2" ]; then
|
||||
cd docs/;
|
||||
retry make linkcheck2;
|
||||
fi
|
||||
|
||||
###
|
||||
### Test Update script
|
||||
###
|
||||
- if [ "${S1}" = "UPDATE" ]; then
|
||||
./update-docker.sh "${V1}";
|
||||
fi
|
||||
|
||||
###
|
||||
### Test Devilbox
|
||||
###
|
||||
- if [ "${S1}" != "MODULES" ] && [ "${S1}" != "DOCUMENTATION" ] && [ "${S1}" != "UPDATE" ]; then
|
||||
cd .tests/;
|
||||
fi
|
||||
- if [ "${S1}" != "MODULES" ] && [ "${S1}" != "DOCUMENTATION" ] && [ "${S1}" != "UPDATE" ]; then
|
||||
if [ "${S1}" != "DOCKER" ]; then
|
||||
retry make configure KEY="${S1}_SERVER" VAL="${V1}";
|
||||
retry make configure KEY="${S2}_SERVER" VAL="${V2}";
|
||||
fi
|
||||
fi
|
||||
- if [ "${S1}" != "MODULES" ] && [ "${S1}" != "DOCUMENTATION" ] && [ "${S1}" != "UPDATE" ]; then
|
||||
retry make start;
|
||||
retry make test-smoke-modules;
|
||||
retry make test-smoke-config;
|
||||
retry make test-smoke-intranet;
|
||||
retry make test-smoke-vendors;
|
||||
retry make test-smoke-vhosts;
|
||||
retry make test-smoke-rproxies;
|
||||
retry make test-smoke-ssl;
|
||||
retry make test-smoke-bind;
|
||||
retry make test-smoke-autostart;
|
||||
retry make test-smoke-framework-cakephp;
|
||||
retry make test-smoke-framework-drupal;
|
||||
retry make test-smoke-framework-wordpress;
|
||||
fi
|
||||
|
||||
@ -26,6 +26,7 @@
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
|
||||
[](https://github.com/cytopia/devilbox/actions?workflow=Lint)
|
||||
[](https://github.com/cytopia/devilbox/actions?workflow=Docs)
|
||||
[](https://github.com/cytopia/devilbox/actions?workflow=Linux)
|
||||
[](https://github.com/cytopia/devilbox/actions?workflow=Config)
|
||||
[](https://github.com/cytopia/devilbox/actions?workflow=Versions)
|
||||
|
||||
@ -1,52 +1,27 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
ifneq (,)
|
||||
.error This Makefile requires GNU Make.
|
||||
endif
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
SPHINXPROJ = devilbox
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
# -------------------------------------------------------------------------------------------------
|
||||
# Default configuration
|
||||
# -------------------------------------------------------------------------------------------------
|
||||
.PHONY: help build autobuild linkcheck linkcheck2
|
||||
|
||||
|
||||
# -------------------------------------------------------------------------------------------------
|
||||
# Default Target
|
||||
# -------------------------------------------------------------------------------------------------
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
@echo
|
||||
@echo "Devilbox additional commands:"
|
||||
@echo "build Build and test documentation"
|
||||
@echo " autobuild Continuously run and build (http://127.0.0.1:8000)"
|
||||
|
||||
.PHONY: help Makefile test build autobuild
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
@echo "autobuild Continuously run and build (http://0.0.0.0:8000)"
|
||||
@echo "linkcheck Sphinx linkcheck"
|
||||
@echo "linkcheck2 Custom linkcheck"
|
||||
|
||||
|
||||
#
|
||||
# Devilbox additions
|
||||
#
|
||||
#
|
||||
# Used Sphinx options:
|
||||
# --------------------
|
||||
#
|
||||
# -a: Always write all output files. The default is to only write output files
|
||||
# for new and changed source files.
|
||||
#
|
||||
# -E: Don’t use a saved environment (the structure caching all cross-references),
|
||||
# but rebuild it completely.
|
||||
#
|
||||
# -n: Run in nit-picky mode. Currently, this generates warnings for all
|
||||
# missing references. See the config value nitpick_ignore for a way to
|
||||
# exclude some references as “known missing”.
|
||||
#
|
||||
# -q: Do not output anything on standard output, only write warnings and errors
|
||||
# to standard error.
|
||||
#
|
||||
# -W: Turn warnings into errors. This means that the build stops at the first
|
||||
# warning and sphinx-build exits with exit status 1.
|
||||
|
||||
# -------------------------------------------------------------------------------------------------
|
||||
# Target
|
||||
# -------------------------------------------------------------------------------------------------
|
||||
|
||||
linkcheck2:
|
||||
ifeq ($(wildcard file1),)
|
||||
@ -57,8 +32,39 @@ endif
|
||||
chmod +x linkcheck
|
||||
./linkcheck -l -k -r 60 -t 30 -e rst _includes/
|
||||
|
||||
linkcheck:
|
||||
docker run \
|
||||
--rm \
|
||||
$$(tty -s && echo "-it" || echo) \
|
||||
-e SPHINX_PROJECT="docs" \
|
||||
-e SPHINX_PORT=8000 \
|
||||
-e NEW_UID="$$(id -u)" \
|
||||
-e NEW_GID="$$(id -g)" \
|
||||
-v $(PWD)/..:/shared/httpd \
|
||||
devilbox/python-sphinx:3.8-dev \
|
||||
sphinx-build -M linkcheck . _build
|
||||
|
||||
build:
|
||||
sphinx-build -a -E -n -j auto -q -W . _build/html
|
||||
docker run \
|
||||
--rm \
|
||||
$$(tty -s && echo "-it" || echo) \
|
||||
-e SPHINX_PROJECT="docs" \
|
||||
-e SPHINX_PORT=8000 \
|
||||
-e NEW_UID="$$(id -u)" \
|
||||
-e NEW_GID="$$(id -g)" \
|
||||
-v $(PWD)/..:/shared/httpd \
|
||||
devilbox/python-sphinx:3.8-dev \
|
||||
sphinx-build -a -E -n -j auto -W . _build/html
|
||||
|
||||
autobuild:
|
||||
sphinx-autobuild . _build/html
|
||||
docker run \
|
||||
--rm \
|
||||
$$(tty -s && echo "-it" || echo) \
|
||||
-e SPHINX_PROJECT="docs" \
|
||||
-e SPHINX_PORT=8000 \
|
||||
-e NEW_UID="$$(id -u)" \
|
||||
-e NEW_GID="$$(id -g)" \
|
||||
-p "8000:8000" \
|
||||
-v $(PWD)/..:/shared/httpd \
|
||||
devilbox/python-sphinx:3.8-dev \
|
||||
sphinx-autobuild -a -E -n -j auto -W -H 0.0.0.0 -p 8000 . _build/html
|
||||
|
||||
@ -19,10 +19,15 @@ You can also build the documentation locally before pushing to ensure everything
|
||||
|
||||
#### Requirements
|
||||
|
||||
* Docker
|
||||
|
||||
#### How to check for broken links
|
||||
```
|
||||
sudo pip install sphinx sphinx-autobuild recommonmark
|
||||
sudo pip install sphinx_rtd_theme
|
||||
cd docs/
|
||||
make linkcheck
|
||||
make linkcheck2
|
||||
```
|
||||
|
||||
#### How to build and error-check
|
||||
```
|
||||
cd docs/
|
||||
@ -37,4 +42,4 @@ make autobuild
|
||||
|
||||
#### How to view
|
||||
|
||||
When using `make autobuild` your documentation is served at: http://127.0.0.1:8000
|
||||
When using `make autobuild` your documentation is served at: http://0.0.0.0:8000
|
||||
|
||||
@ -78,6 +78,8 @@ language = None
|
||||
exclude_patterns = [
|
||||
u'_build/*',
|
||||
u'_includes/**',
|
||||
u'venv/**',
|
||||
u'requirements.txt',
|
||||
u'Thumbs.db',
|
||||
u'.DS_Store'
|
||||
]
|
||||
|
||||
2
docs/requirements.txt
Normal file
2
docs/requirements.txt
Normal file
@ -0,0 +1,2 @@
|
||||
recommonmark
|
||||
sphinx_rtd_theme
|
||||
Loading…
Reference in New Issue
Block a user