From 1b70641b1df83c0293ddf277228868d1c7189262 Mon Sep 17 00:00:00 2001 From: "Frank de Graaf (Phally)" Date: Sat, 30 May 2020 11:31:40 +0200 Subject: [PATCH 1/6] Updates Docker build and documentation. --- CONTRIBUTING.md | 7 ++++--- docs/Dockerfile | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7af67d541..74d5e8538 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,11 @@ # How to contribute Crud loves to welcome your contributions. There are several ways to help out: + * Create a ticket in GitHub, if you have found a bug * Write testcases for open bug tickets * Write patches for open bug/feature tickets, preferably with testcases included -* Contribute to the [documentation](https://github.com/friendsofcake/crud/tree/gh-pages) +* Contribute to the [documentation](https://github.com/FriendsOfCake/crud/tree/master/docs) There are a few guidelines that we need contributors to follow so that we have a chance of keeping on top of things. @@ -67,10 +68,10 @@ You can build the documentation using Docker via the following commands: cd docs # build the docs - docker build . + docker build -t friendsofcake/crud . # make the html - docker run -it --rm -v $(pwd)/docs:/data friendsofcake/crud make html + docker run -it --rm -v $(pwd):/data friendsofcake/crud make html # open the generated html docs in docs/_build/html diff --git a/docs/Dockerfile b/docs/Dockerfile index 8db8df7fa..aca3c9b1b 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -1,4 +1,4 @@ -FROM debian:jessie +FROM debian:buster ENV DEBIAN_FRONTEND noninteractive From 0cff56a7ed85a5b1b866d7b3a0063fd2f187a803 Mon Sep 17 00:00:00 2001 From: "Frank de Graaf (Phally)" Date: Sat, 30 May 2020 15:09:57 +0200 Subject: [PATCH 2/6] Adds Browser Sync config for docs. --- CONTRIBUTING.md | 3 +++ docs/browser-sync-config.js | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) create mode 100644 docs/browser-sync-config.js diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 74d5e8538..525a24802 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -75,6 +75,9 @@ You can build the documentation using Docker via the following commands: # open the generated html docs in docs/_build/html + # or use Browser Sync with automatic builds and browser refresh on file save + browser-sync start --config browser-sync-config.js + # Additional Resources * [CakePHP coding standards](http://book.cakephp.org/2.0/en/contributing/cakephp-coding-conventions.html) diff --git a/docs/browser-sync-config.js b/docs/browser-sync-config.js new file mode 100644 index 000000000..1dcb4fc59 --- /dev/null +++ b/docs/browser-sync-config.js @@ -0,0 +1,33 @@ +const { exec } = require("child_process"); + +const docker = "docker run --rm -v $(pwd):/data friendsofcake/crud make html"; + +module.exports = { + server: { + baseDir: "_build/html", + index: "index.html" + }, + + files: [ + "_build/html/*.html", + { + match: ["**/*.rst", "**/*.php"], + fn: (event) => { + if (event !== 'change') { + return false; + } + exec(docker, (error, stdout, stderr) => { + if (error) { + console.error(error); + return; + } + console.log(stdout); + }); + return false; + }, + options: { + ignored: '_build' + } + } + ] +}; From 23e82183cd10c583398c8fb7fb4a917a4a7912cd Mon Sep 17 00:00:00 2001 From: "Frank de Graaf (Phally)" Date: Sat, 30 May 2020 16:18:48 +0200 Subject: [PATCH 3/6] Also test build docs with Travis CI. --- .travis.yml | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/.travis.yml b/.travis.yml index 73d75b096..787a05667 100644 --- a/.travis.yml +++ b/.travis.yml @@ -17,6 +17,7 @@ env: - DB=sqlite db_dsn='sqlite:///:memory:' global: - DEFAULT=1 + - PHP=1 matrix: fast_finish: true @@ -31,11 +32,23 @@ matrix: - php: 5.6 env: PREFER_LOWEST=1 + - language: python + python: 2.7 + env: DOCS=1 PHP=0 DEFAULT=0 + install: + - pip install -r docs/requirements.txt + addons: + apt: + packages: + - texlive-latex-recommended + - texlive-latex-extra + - texlive-fonts-recommended + before_script: - - if [[ $TRAVIS_PHP_VERSION != 7.1 ]]; then phpenv config-rm xdebug.ini; fi + - if [[ $PHP = 1 && $TRAVIS_PHP_VERSION != 7.1 ]]; then phpenv config-rm xdebug.ini; fi - - if [[ $PREFER_LOWEST != 1 ]]; then composer install --no-interaction; fi - - if [[ $PREFER_LOWEST = 1 ]]; then composer update --no-interaction --prefer-lowest --prefer-stable; fi + - if [[ $PHP = 1 && $PREFER_LOWEST != 1 ]]; then composer install --no-interaction; fi + - if [[ $PHP = 1 && $PREFER_LOWEST = 1 ]]; then composer update --no-interaction --prefer-lowest --prefer-stable; fi - if [[ $DB = 'mysql' ]]; then mysql -e 'CREATE DATABASE cakephp_test;'; fi - if [[ $DB = 'pgsql' ]]; then psql -c 'CREATE DATABASE cakephp_test;' -U postgres; fi @@ -50,6 +63,8 @@ script: - if [[ $PHPCS = 1 ]]; then vendor/bin/phpcs -p --extensions=php --standard=vendor/cakephp/cakephp-codesniffer/CakePHP ./src ./tests; fi - if [[ $PHPSTAN = 1 ]]; then vendor/bin/phpstan analyse -c phpstan.neon -l 4 src; fi + - if [[ $DOCS = 1 ]]; then cd docs && make html && find _build/html -type f; fi + after_success: - if [[ $DEFAULT = 1 && $TRAVIS_PHP_VERSION = 7.1 ]]; then bash <(curl -s https://codecov.io/bash); fi From 607f4e907620ac868ccba3bf402d56051abb38f0 Mon Sep 17 00:00:00 2001 From: "Frank de Graaf (Phally)" Date: Sat, 30 May 2020 18:01:43 +0200 Subject: [PATCH 4/6] Upgrade to Python 3. --- .travis.yml | 2 +- docs/Dockerfile | 4 ++-- docs/Makefile | 2 +- docs/requirements.txt | 20 ++------------------ 4 files changed, 6 insertions(+), 22 deletions(-) diff --git a/.travis.yml b/.travis.yml index 787a05667..5bfccde59 100644 --- a/.travis.yml +++ b/.travis.yml @@ -33,7 +33,7 @@ matrix: env: PREFER_LOWEST=1 - language: python - python: 2.7 + python: 3.7 env: DOCS=1 PHP=0 DEFAULT=0 install: - pip install -r docs/requirements.txt diff --git a/docs/Dockerfile b/docs/Dockerfile index aca3c9b1b..c3947812c 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -5,7 +5,7 @@ ENV DEBIAN_FRONTEND noninteractive LABEL Description="This image is used to create an environment to contribute to the crud/docs" RUN apt-get update && apt-get install -y \ - python-pip \ + python3-pip \ texlive-latex-recommended \ texlive-latex-extra \ texlive-fonts-recommended \ @@ -13,7 +13,7 @@ RUN apt-get update && apt-get install -y \ && rm -rf /var/lib/apt/lists/* COPY requirements.txt /tmp/ -RUN pip install -r /tmp/requirements.txt +RUN pip3 install -r /tmp/requirements.txt WORKDIR /data diff --git a/docs/Makefile b/docs/Makefile index 5ccce544e..789aa7bb8 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,7 +5,7 @@ SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build -PYTHON = python +PYTHON = python3 LANG = en # Internal variables. diff --git a/docs/requirements.txt b/docs/requirements.txt index d70e799d9..04130f185 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,19 +1,3 @@ -alabaster==0.7.12 -Babel==2.3.4 -certifi==2018.11.29 -chardet==3.0.4 -docutils==0.14 -idna==2.7 -imagesize==0.7.1 -Jinja2==2.10.1 -MarkupSafe==0.23 -Pygments==2.3.0 -pytz==2018.7 -requests==2.20.1 -six==1.11.0 -snowballstemmer==1.2.1 -Sphinx==1.5.1 -sphinx-rtd-theme==0.1.9 -sphinxcontrib-phpdomain==0.2.1 -urllib3==1.24.2 +sphinx==1.8.5 +sphinxcontrib-phpdomain==0.7.0 cakephp-theme From e86a439718616e7ff9a30facde1b97db6d3db347 Mon Sep 17 00:00:00 2001 From: "Frank de Graaf (Phally)" Date: Sat, 30 May 2020 19:38:13 +0200 Subject: [PATCH 5/6] Adds Rstcheck to lint the docs. --- .travis.yml | 1 + docs/requirements.txt | 1 + 2 files changed, 2 insertions(+) diff --git a/.travis.yml b/.travis.yml index 5bfccde59..76c7576ed 100644 --- a/.travis.yml +++ b/.travis.yml @@ -63,6 +63,7 @@ script: - if [[ $PHPCS = 1 ]]; then vendor/bin/phpcs -p --extensions=php --standard=vendor/cakephp/cakephp-codesniffer/CakePHP ./src ./tests; fi - if [[ $PHPSTAN = 1 ]]; then vendor/bin/phpstan analyse -c phpstan.neon -l 4 src; fi + - if [[ $DOCS = 1 ]]; then cd docs && rstcheck -r . && cd -; fi - if [[ $DOCS = 1 ]]; then cd docs && make html && find _build/html -type f; fi after_success: diff --git a/docs/requirements.txt b/docs/requirements.txt index 04130f185..b295a313b 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ sphinx==1.8.5 sphinxcontrib-phpdomain==0.7.0 +rstcheck==3.3.1 cakephp-theme From b5e0814d5e75fe2a2f4482634d98db73fd53c3e5 Mon Sep 17 00:00:00 2001 From: "Frank de Graaf (Phally)" Date: Sat, 30 May 2020 20:22:06 +0200 Subject: [PATCH 6/6] Fixes rstcheck result. --- docs/.rstcheck.cfg | 2 ++ docs/unit-testing.rst | 6 +++--- 2 files changed, 5 insertions(+), 3 deletions(-) create mode 100644 docs/.rstcheck.cfg diff --git a/docs/.rstcheck.cfg b/docs/.rstcheck.cfg new file mode 100644 index 000000000..e835d6eb5 --- /dev/null +++ b/docs/.rstcheck.cfg @@ -0,0 +1,2 @@ +[rstcheck] +report=warning diff --git a/docs/unit-testing.rst b/docs/unit-testing.rst index 42c4aa21f..2ca5dc39a 100644 --- a/docs/unit-testing.rst +++ b/docs/unit-testing.rst @@ -3,9 +3,9 @@ Unit Testing ************ To ease with unit testing of Crud Listeners and Crud Actions, it's recommended -to use the proxy methods found in [CrudBaseObject]({{site.url}}/api/develop/class-CrudBaseObject.html). +to use the proxy methods found in :code:`CrudBaseObject`. -These methods are much easier to mock than the full `CrudComponent` object. +These methods are much easier to mock than the full :code:`CrudComponent` object. They also allow you to just mock the methods you need for your specific test, rather than the big dependency nightmare the CrudComponent can be in some cases. @@ -13,7 +13,7 @@ CrudComponent can be in some cases. Proxy methods ============= -These methods are available in all `CrudAction` and `CrudListener` objects. +These methods are available in all :code:`CrudAction` and :code:`CrudListener` objects. _crud() -------