Impoved docs build

.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: 3.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,9 @@ 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:
   - if [[ $DEFAULT = 1 && $TRAVIS_PHP_VERSION = 7.1 ]]; then bash <(curl -s https://codecov.io/bash); fi
 

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,13 +68,16 @@ 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
 
+    # 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)

docs/.rstcheck.cfg

@@ -0,0 +1,2 @@
+[rstcheck]
+report=warning

docs/Dockerfile

@@ -1,19 +1,19 @@
-FROM debian:jessie
+FROM debian:buster
 
 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 \
   && apt-get clean \
   && 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
 

docs/Makefile

@@ -5,7 +5,7 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
-PYTHON        = python
+PYTHON        = python3
 LANG          = en
 
 # Internal variables.

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'
+      }
+    }
+  ]
+};

docs/requirements.txt

@@ -1,19 +1,4 @@
-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
+rstcheck==3.3.1
 cakephp-theme

docs/unit-testing.rst

@@ -3,17 +3,17 @@ 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.
 
 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()
 -------