diff --git a/.gitignore b/.gitignore index 60607d7..a665241 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,6 @@ .idea +.vscode +docs/build tests/bats tests/test_helper diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..a5b1156 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,29 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.9" + # You can also specify other tool versions: + # nodejs: "19" + # rust: "1.64" + # golang: "1.19" + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + +# If using Sphinx, optionally build your docs in additional formats such as PDF +# formats: +# - pdf + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: docs/requirements.txt diff --git a/commands/doxygen/dkan-docs b/commands/doxygen/dkan-docs deleted file mode 100644 index 0a95997..0000000 --- a/commands/doxygen/dkan-docs +++ /dev/null @@ -1,14 +0,0 @@ -#!/bin/bash -#ddev-generated -## Description: Generate documentation for the DKAN module. -## -## Usage: dkan-docs [arguments] -## Flags: [] -## Example: "ddev dkan-docs" - -DOCS_PATH="modules/contrib/dkan" - -cd docroot/$DOCS_PATH -doxygen "$@" - -echo " * Documentation is now available at: $DDEV_PRIMARY_URL/$DOCS_PATH/docs/index.html" diff --git a/docker-compose.doxygen.yaml b/docker-compose.doxygen.yaml deleted file mode 100644 index a817e37..0000000 --- a/docker-compose.doxygen.yaml +++ /dev/null @@ -1,32 +0,0 @@ -# Run Doxygen. -#ddev-generated -version: '3.6' -services: - doxygen: - container_name: ddev-${DDEV_SITENAME}-doxygen - - build: - context: './doxygen-build' - args: - BASE_IMAGE: debian:bullseye-slim - - labels: - com.ddev.site-name: ${DDEV_SITENAME} - com.ddev.platform: ddev - com.ddev.app-type: php - com.ddev.approot: $DDEV_APPROOT - volumes: - - "../:/var/www/html:cached" - - ".:/mnt/ddev_config" - - environment: - - DDEV_PRIMARY_URL=${DDEV_PRIMARY_URL} - - external_links: - # Resolve links via DDEV router - - "ddev-router:${DDEV_HOSTNAME}" - - working_dir: /var/www/html - entrypoint: "/bin/bash" - tty: true - networks: ["default","ddev_default"] diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..ed88099 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# 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) diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index c741881..0000000 --- a/docs/_config.yml +++ /dev/null @@ -1 +0,0 @@ -theme: jekyll-theme-slate \ No newline at end of file diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 0000000..a9e36ee --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,3 @@ +.wy-side-nav-search > div.version { + color: white; +} diff --git a/docs/_static/dkan.png b/docs/_static/dkan.png new file mode 100644 index 0000000..0923e61 Binary files /dev/null and b/docs/_static/dkan.png differ diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100644 index 0000000..2cffba7 Binary files /dev/null and b/docs/_static/favicon.ico differ diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..2a57b78 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,72 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +#sys.path.insert(0, os.path.abspath('../../modules/')) +#sys.path.append(os.path.abspath('..')) + + +# -- Project information ----------------------------------------------------- + +project = 'DKAN DDEV Addon Documentation' +copyright = '2023, CivicActions' +author = 'CivicActions' + +# The full version, including alpha/beta/rc tags +version = '1.x' + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +# sphinxcontrib-phpdomain is not compatible with myst. +extensions = [ + 'myst_parser', + 'sphinx_rtd_theme', + 'sphinx_prompt' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] +html_css_files = ['custom.css'] +html_logo = '' +html_favicon = '_static/dkan.png' + +# The suffix of source filenames. +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} +source_parsers = {'.md': 'myst_parser.sphinx_'} + +autosectionlabel_prefix_document = True +autosectionlabel_maxdepth=None diff --git a/docs/demo.md b/docs/demo.rst similarity index 72% rename from docs/demo.md rename to docs/demo.rst index 5763121..8a9a1ba 100644 --- a/docs/demo.md +++ b/docs/demo.rst @@ -1,16 +1,23 @@ -# Run The DKAN Demo Site +Run The DKAN Demo Site +====================== Note: As of DDev 1.19.5, these instructions require managing the settings.php file. After DDev 1.19.6 is released, this will (hopefully) not be required. +.. prompt:: bash $ + mkdir my-project && cd my-project ddev config --auto ddev get getdkan/dkan-ddev-addon ddev restart ddev composer create getdkan/recommended-project:@dev -y - # At this point, we must add a configuration to settings.php - # This should change after DDev 1.19.6 is released. + +At this point, we must add a configuration to settings.php + +This should change after DDev 1.19.6 is released. + +.. prompt:: bash $ + cat .ddev/misc/settings.dkan-snippet.php.txt >> docroot/sites/default/settings.php cp .ddev/misc/settings.dkan.php docroot/sites/default/settings.dkan.php - ddev dkan-demo diff --git a/docs/dktl-convert.md b/docs/dktl-convert.rst similarity index 84% rename from docs/dktl-convert.md rename to docs/dktl-convert.rst index 1954733..c0ce877 100644 --- a/docs/dktl-convert.md +++ b/docs/dktl-convert.rst @@ -1,42 +1,55 @@ -# Convert DKAN-Tools project to DDEV +Convert DKAN-Tools project to DDEV +================================== Note: This documentation is incomplete. -## Codebase: +Codebase: +--------- -### Prepare the site for conversion +Prepare the site for conversion +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The main steps here would be to ensure a fresh config export and add it to your repo. This might or might not be necessary, but is probably a best practice anyway. -### Get the web root from composer.json. +Get the web root from composer.json. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Look at the project composer.json file. It will likely have an `extra.drupal-scaffold.locations.web-root` configuration. Make a note of that. It's probably `docroot/` -### Initially configure DDEV. +Initially configure DDEV. +^^^^^^^^^^^^^^^^^^^^^^^^^^ Use the web root information to configure DDEV: +.. prompt:: bash $ + cd your_project_root ddev config --project-type drupal9 --docroot YOUR_WEBROOT_VALUE --create-docroot This command will set up an initial state of configuration. We're going to override this with the dkan-ddev-addon in the next step, but DDEV requires that we do this first. -### Get the DKAN DDEV addon. +Get the DKAN DDEV addon. +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. prompt:: bash $ ddev get https://github.com/GetDKAN/dkan-ddev-addon/archive/refs/heads/main.tar.gz ddev restart This will pull down some configuration and scripts. We must then restart the DDEV environment after this. -### Set up `.gitignore`. +Set up `.gitignore`. +^^^^^^^^^^^^^^^^^^^^^ For now, we'll just delete the current `.gitignore` for the project and only ignore the vendor directory. Alternately, if you don't want to lose the contents of `.gitignore` you could rename it. +.. code-block:: + rm .gitignore # Alternately: mv .gitignore old.gitignore echo "vendor/" >> .gitignore @@ -45,19 +58,25 @@ This will cause the Drupal Composer Scaffold plugin to add scaffolded files to t We'll fill out the rest of the `.gitignore` file at the end. -### Initial Composer install. +Initial Composer install. +^^^^^^^^^^^^^^^^^^^^^^^^^ Now let's use DDEV to run `composer install`, so it can build out some directories for us, to make subsequent steps easier. +.. prompt:: bash $ + ddev composer install During this process, Composer might ask you if it's OK for plugins to run, and it's probably OK to answer yes. You might end up answering 'yes' to a number of questions like this: +.. code-block:: + Do you trust "drupal/core-composer-scaffold" to execute code and wish to enable it now? (writes "allow-plugins" to composer.json) [y,n,d,?] -### Manage the tests, modules, and themes. +Manage the tests, modules, and themes. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The repo likely contains a `src/` directory, and within that `src/modules`. This is where the custom modules for your site live. @@ -68,27 +87,37 @@ web root directory, use that instead.) When we're done, the contents of `src/mod We'll do the same thing for themes, as well. +.. prompt:: bash $ + mv src/modules docroot/modules/custom mv src/themes docroot/themes/custom Your site might also have tests under `src/tests`. You should move these tests to `tests/`, so that the project-level test runner can find them. +.. prompt:: bash $ + mv src/tests tests/ -### Schema +Schema +^^^^^^ DKAN uses a special directory called `schema/`. This directory is located in `src/schema/` under DKAN-Tools, and much like the modules and themes above we should move it. +.. prompt:: bash $ + mv src/schema docroot/ -### Settings..? Settings. +Settings..? Settings. +^^^^^^^^^^^^^^^^^^^^^^ Let's state up-front that it's complicated here. First of all, we'll follow the instructions for the DKAN DDEV addon, and add the DKAN-specific config to settings.php. +.. prompt:: bash $ + cat .ddev/misc/settings.dkan-snippet.php.txt >> docroot/sites/default/settings.php cp .ddev/misc/settings.dkan.php docroot/sites/default/settings.dkan.php @@ -103,49 +132,70 @@ or what could be another external file which is loaded by `settings.php`. Candidates for things which are important might include config sync location, and the site hash value. -### A complete codebase? Let's try and install... +A complete codebase? Let's try and install. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Well, maybe our codebase isn't complete. Did you already have Drush? Let's ask Composer. +.. prompt:: bash $ + ddev composer show drush/drush | grep versions If you don't see a version number, add Drush: +.. prompt:: bash $ + ddev composer require drush/drush OK, *now* we can install a site. If your site uses the DKAN module, use `ddev dkan-site-install`. Otherwise just use Drush. +.. prompt:: bash $ + ddev dkan-site-install - # or... + +or... + +.. prompt:: bash $ + ddev drush site-install -y This gives us a plain-vanilla Drupal installation. Launch it and behold its beauty: +.. prompt:: bash $ + ddev launch Note that we're seeing aggregated CSS and JS being sent with a MIME type of text/hml, which modern browsers refuse to show. If your site looks like it doesn't have CSS, you can use Drush to turn off aggregation, for now: +.. prompt:: bash $ + ddev drush -y config-set system.performance css.preprocess 0 ddev drush -y config-set system.performance js.preprocess 0 Log in if you'd like: +.. prompt:: bash $ + ddev drush uli -### Import our config +Import our config +^^^^^^^^^^^^^^^^^ This is really two steps. The site we're converting probably has some special commands required to get it into a state for importing the configuration, so we'll explore that first. -#### Replicate DKAN-Tools Install Process +Replicate DKAN-Tools Install Process +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Your DKAN-Tools site might have some installation steps in its commands. So look at `src/command`, and look for a command method such as `YoursiteInstall()`. This probably has some Drush commands which you should emulate. For instance, here's a custom DKAN-Tools command from a project: +.. code-block:: + class MyprojectCommands extends Tasks { public function MyprojectInstall() { @@ -165,6 +215,8 @@ For instance, here's a custom DKAN-Tools command from a project: From this we can remove the `dktl install` command (since that's the same as `ddev dkan-site-install`), and then extract the rest and replace `dktl` with `ddev` to run Drush. This give us a list like this: +.. code-block:: + ddev drush entity:delete shortcut_set ddev drush pmu shortcut ddev drush config:set system.site uuid [YOUR UUID HERE] -y @@ -182,25 +234,33 @@ configuration. For bonus points, you can [convert this command to a DDEV command](https://ddev.readthedocs.io/en/latest/users/extend/custom-commands/) which users can then use from then on whenever you install Drupal. -#### Import Site Configuration +Import Site Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~ Now that you've replicated your site's DKAN-Tools install command, you can import the site config. +.. prompt:: bash $ + ddev drush cim -### Did it work? +Did it work? +^^^^^^^^^^^^ Let's find out: +.. prompt:: bash $ + ddev drush cr ddev launch Handy commands for finding out what went wrong include: - ddev logs +.. prompt:: bash $ -### Finalize `.gitignore` for the repo + ddev logs +Finalize `.gitignore` for the repo +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ We can see that Drupal core has provided us with a handy file called `docroot/example.gitignore`. We can copy this file to be `docroot/.gitignore` and it will hide files from Git, such as configuration and public file @@ -208,8 +268,11 @@ directories. We also want to read that file, so we can fully understand what it does, and modify it for our project-related needs. +.. prompt:: bash $ + mv docroot/example.gitignore docroot/.gitignore - # Read and modify docroot/.gitignore as needed... + +Read and modify docroot/.gitignore as needed... Alternately, we could move all the rules from `example.gitignore` to our root-level `.gitignore`. Whether to do this is an exercise left to the leader of your project. @@ -218,6 +281,8 @@ Also we should visit our top-level `.gitignore` file so we can be sure we don't Here's a `.gitignore` file which leaves out all the things you can rebuild with Composer. +.. code-block:: + vendor/ /.editorconfig /.gitattributes @@ -228,4 +293,6 @@ Here's a `.gitignore` file which leaves out all the things you can rebuild with You probably want to exclude IDE settings: +.. code-block:: + .idea/ diff --git a/docs/docs.md b/docs/docs.md deleted file mode 100644 index a7f2728..0000000 --- a/docs/docs.md +++ /dev/null @@ -1,9 +0,0 @@ -# DKAN Documentation - -You can generate documentation for DKAN module with this command: - - ddev dkan-docs - -You can add doxygen arguments after the command as needed. - -Currently, you'll find the generated documentation at `[path to]/dkan/docs`. diff --git a/docs/frontend.md b/docs/frontend.rst similarity index 84% rename from docs/frontend.md rename to docs/frontend.rst index 27b9a0c..e8e5a64 100644 --- a/docs/frontend.md +++ b/docs/frontend.rst @@ -1,19 +1,26 @@ -# Frontend Application Management +Frontend Application Management +=============================== DKAN includes a decoupled front-end application to display and query data. This front end can be managed using the following tools: +.. prompt:: bash $ + ddev dkan-frontend-install ddev dkan-frontend-build Note that in order to install the frontend, you must have previously run: +.. prompt:: bash $ + ddev dkan-init ddev dkan-site-install When it comes time for testing: +.. prompt:: bash $ + ddev dkan-frontend-test The dkan-frontend-test is intended for CI processes. Users are encouraged to diff --git a/docs/getting-started.md b/docs/getting-started.rst similarity index 68% rename from docs/getting-started.md rename to docs/getting-started.rst index 272417b..418f8e2 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.rst @@ -1,45 +1,63 @@ -# Getting started with DKAN DDev Addon +Getting started with DKAN DDEV Add-on +==================================== -## Start a new DKAN site +Start a new DKAN site +--------------------- First, make a directory for your project. +.. prompt:: bash $ + mkdir my-project && cd my-project -Give DDev just enough configuration to get started. +Give DDEV just enough configuration to get started. + +.. prompt:: bash $ ddev config --auto -Grab the DKAN addon to get helpful DKAN commands. +Grab the DKAN add-on to get helpful DKAN commands. Note that eventually we'll be 'official' and you won't have to install this from a tarball. +.. prompt:: bash $ + ddev get https://github.com/GetDKAN/dkan-ddev-addon/archive/refs/heads/main.tar.gz Make sure we're using the addon. +.. prompt:: bash $ + ddev restart Initialize the site. +.. prompt:: bash $ + ddev dkan-init This will ask you if it's OK to remove most of the files in your project. You can answer yes since there's nothing there right now anyway. Now install Drupal. +.. prompt:: bash $ + ddev dkan-site-install Now we have a useful DKAN-based Drupal site, so let's take a look, and use the standard tools to log in: +.. prompt:: bash $ + ddev launch ddev drush status-report ddev drush uli -Note that if you need help with any of the DDev commands, you can add `--help` +Note that if you need help with any of the DDEV commands, you can add `--help` on the command line and get help: +.. code-block:: + ddev dkan-init --help Build the Drupal codebase for a DKAN site. (shell host container command) @@ -59,41 +77,54 @@ on the command line and get help: Global Flags: -j, --json-output If true, user-oriented output will be in JSON format. -## Contributing to DKAN +Contributing to DKAN +-------------------- If you are doing development work on the DKAN module itself, add the --moduledev flag to the dkan-init command: +.. prompt:: bash $ + ddev dkan-init --moduledev This will clone the dkan project into its own directory and tell Composer to use that repo as the getdkan/dkan package. -## Decoupled Frontend app installation and build +Decoupled Frontend app installation and build +--------------------------------------------- -DKAN can integrate with a JS/headless app. The DKAN DDev addon has special +DKAN can integrate with a JS/headless app. The DKAN DDEV addon has special commands for dealing with this. -### Install +Install +^^^^^^^ First we gather all the dependencies and files necessary for the frontend: +.. prompt:: bash $ + ddev dkan-frontend-install -### Build +Build +^^^^^ Now that you have all the dependencies, you can build the frontend: +.. prompt:: bash $ + ddev dkan-frontend-build Currently this command essentially calls `npm run build` within the web container -of DDev. +of DDEV. -## Additional Commands +Additional Commands +------------------- Run `ddev` by itself to get a list of commands available to you. Run `ddev get --list --all` to get a list of other DDEV add-ons. -## Additional Resources -- [DDEV Documentation](https://ddev.readthedocs.io/en/stable/users/usage/) -- [DKAN Documentation](https://demo.getdkan.org/modules/contrib/dkan/docs/index.html) +Additional Resources +-------------------- + +- `DDEV Documentation `_ +- `DKAN Documentation `_ diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index ccaa9b0..0000000 --- a/docs/index.md +++ /dev/null @@ -1,30 +0,0 @@ -# DKAN DDev Addon - -The DKAN DDEv Addon provides configuration and specialized commands for dealing -with a DKAN Drupal project in the DDEv environment. - -Note that all the DKAN commands which come with this addon have documentation built-in. At the command line, you can -ask for help with any one of them with `ddev [command] --help` like this: - - % ddev dkan-init --help - Build the Drupal codebase for a DKAN site. (shell host container command) - - Usage: - ddev dkan-init [flags] - - Flags: - -h, --help help for dkan-init - --moduledev Set up the file system for DKAN module development. - - Global Flags: - -j, --json-output If true, user-oriented output will be in JSON format. - -## Sections: - -- [Getting started](getting-started.md) -- [Create a demo DKAN site](demo.md) -- [Convert a DKAN-Tools project to DDEV](dktl-convert.md) -- [Testing the DKAN module](testing-dkan.md) -- [Debugging PHPUnit tests in DDev](testing-debug-phpunit.md) -- [Testing your local development project](testing-project.md) -- [Generate DKAN Documentation](docs.md) diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..3ef77c6 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,35 @@ +DKAN DDEV Addon +=============== + +The DKAN DDEV Add-on provides configuration and specialized commands for dealing +with a DKAN Drupal project in the DDEV environment. + +Note that all the DKAN commands which come with this addon have documentation built-in. At the command line, you can +ask for help with any one of them with `ddev [command] --help` like this: + +.. code-block:: + + ddev dkan-init --help + Build the Drupal codebase for a DKAN site. (shell host container command) + + Usage: + ddev dkan-init [flags] + + Flags: + -h, --help help for dkan-init + --moduledev Set up the file system for DKAN module development. + + Global Flags: + -j, --json-output If true, user-oriented output will be in JSON format. + +.. toctree:: + :maxdepth: 1 + + getting-started + frontend + demo + dktl-convert + testing-debug-phpunit + testing-dkan + testing-project + diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..a889287 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +myst-parser>=2.0.0 +sphinx==7.2.6 +sphinx-rtd-theme>=1.2.2 +pygments>=2.14 +sphinx-prompt>=1.8.0 diff --git a/docs/testing-debug-phpunit.md b/docs/testing-debug-phpunit.rst similarity index 84% rename from docs/testing-debug-phpunit.md rename to docs/testing-debug-phpunit.rst index 237a98c..3bb034a 100644 --- a/docs/testing-debug-phpunit.md +++ b/docs/testing-debug-phpunit.rst @@ -1,4 +1,5 @@ -# Debugging a PHPUnit test with DDev +Debugging a PHPUnit test with DDev +================================== This documentation is specific to using the DKAN DDev addon, but can be generalized for many other use-cases. @@ -6,7 +7,8 @@ generalized for many other use-cases. Currently, we're only going to talk about using PHPStorm. Do you have instructions for another IDE? Make a pull request. :-) -## Goals +Goals +------ We want to be able to use our DDev environment to do step-debugging for PHPUnit-based tests, using PHPStorm. @@ -15,18 +17,20 @@ There are three main moving parts in this process: - The PHPUnit framework configuration. - The Run/Debug test runner. -## 1. Set up the remote PHP interpreter +1. Set up the remote PHP interpreter +------------------------------------ We *could* spend a lot of time working really hard to set up the remote PHP interpreter configuration in PHPStorm to use our DDev environment. -Or, we could install the [DDev Integration plugin](https://plugins.jetbrains.com/plugin/18813-ddev-integration). +Or, we could install the `DDev Integration plugin `_. The plugin is the better choice. It will configure a remote interpreter for you, and you're done. It also gives you some UI clicky things to start and stop DDev environments, among other minor luxuries. -## 2. Configure the PHPUnit framework +2. Configure the PHPUnit framework +---------------------------------- This step will generally tell PHPStorm how to deal with PHPUnit. We're using this to enable step debugging, but this also unlocks some nice features such as in-document @@ -43,7 +47,8 @@ test coverage reporting. - Leave the default configuration and bootstrap file fields empty. - Click 'Apply' and 'OK'. -## 3. Set up a Run/Debug test runner +3. Set up a Run/Debug test runner +--------------------------------- This is the 'script' you want to run the tests. The secret sauce to making this easy to set up is that our phpunit.xml file contains as much of the configuration as possible. @@ -72,16 +77,21 @@ Now that you know where your DKAN module is located, you can create the Run/Debu This is the end of the easy part. Now comes the two complicated things: -### A) Environment variables +a) Environment variables +^^^^^^^^^^^^^^^^^^^^^^^^ In order for the PHPStorm-based test to access our database and see our site, we have to send in some environmental variables. These can be a pain to discover, and they differ for every site. Therefore, we've added a DDev command for it: +.. prompt:: bash $ + ddev dkan-get-env-for-phpunit This command will output something like this: +.. code-block:: + DRUPAL_ROOT=/var/www/html/docroot SIMPLETEST_BASE_URL=https://dkan-core.ddev.site SIMPLETEST_DB=mysql://db:db@dkan-core-db:3306/db @@ -91,17 +101,22 @@ These are the three environmental variables you need in order to run Drupal PHPU On a Mac you can pipe this into the copy/paste: +.. prompt:: bash $ + ddev dkan-get-env-for-phpunit | pbcopy Now head back to the test runner configuration and paste that in for environmental variables. -### B) Create fixture users using external tools +b) Create fixture users using external tools +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you jumped the gun and clicked 'Apply' and 'OK' at this point, and tried to run the tests, you might have some success with the runner. However, you'd see a lot of test fails. That's because for DKAN, we must create users on the Drupal site. The DKAN addon allows for this with this command: +.. prompt:: bash $ + ddev dkan-test-users Now we can fill out the 'Before launch' part of the Run/Debug configuration. @@ -116,7 +131,8 @@ Now we can fill out the 'Before launch' part of the Run/Debug configuration. - Click 'OK' and 'OK' again on the external tools window. - Now you can 'Apply' and 'OK' on the Run/Debug configuration form. -## 4. Let's run the tests +4. Let's run the tests +---------------------- - Ensure the Run/Debug dropdown has the config you just created. - Click the little green play button next to it. @@ -126,13 +142,14 @@ Eventually the tests will finish and you'll know if they are passing. Congratulations, you have configured the IDE to run the tests. -## 5. [Step Debugging with Xdebug](https://ddev.readthedocs.io/en/latest/users/debugging-profiling/step-debugging/) +5. `Step Debugging with Xdebug `_ +------------------------------------------------------------------------------------------------------------------- - Tell DDev to use XDebug: `ddev xdebug on`. - Xdebug’s default port is 9003. - Configure your IDE - * [VS Code](https://ddev.readthedocs.io/en/latest/users/debugging-profiling/step-debugging/#visual-studio-code-vs-code-debugging-setup) - * [PHPStorm](https://ddev.readthedocs.io/en/latest/users/debugging-profiling/step-debugging/#phpstorm-debugging-setup) + * `VS Code `_ + * `PHPStorm `_ - Run `ddev start` if you get an error like "Could not connect to debugging client." The IDE might have stopped at the first line of PHPUnit. You can tell it to run again in the debug pane, but you can diff --git a/docs/testing-dkan.md b/docs/testing-dkan.rst similarity index 78% rename from docs/testing-dkan.md rename to docs/testing-dkan.rst index 1b8a0a0..aeb3611 100644 --- a/docs/testing-dkan.md +++ b/docs/testing-dkan.rst @@ -1,32 +1,42 @@ -# Testing the DKAN module +Testing the DKAN module +======================= -## Testing with PHPUnit +Testing with PHPUnit +--------------------- Your process should set up the site: - ddev dkan-init - # optionally: ddev dkan-init --moduledev +.. prompt:: bash $ + + ddev dkan-init --moduledev ddev dkan-site-install Then run the tests: +.. prompt:: bash $ + ddev dkan-phpunit The tests will run by default with xdebug in "coverage" mode, to facilitate building coverage reports in XML or HTML. If you want to use a step debugger locally, add the `--debug` flag before any other flags or arguments. -## Testing with Cypress locally +Testing with Cypress locally +---------------------------- You will need a locally-installed Cypress binary, version 8. (DKAN frontend and module tests currently require Cypress 8.7) +.. prompt:: bash $ + npm install --location=global cypress@8.7 npx cypress verify npx cypress info Now use ddev to build a site and then test it. +.. prompt:: bash $ + mkdir myproject && cd myproject ddev config --auto ddev get https://github.com/GetDKAN/dkan-ddev-addon/archive/refs/heads/main.tar.gz @@ -36,10 +46,14 @@ Now use ddev to build a site and then test it. Now you can test the site: +.. prompt:: bash $ + ddev dkan-module-test-cypress And you can substitute the local dev DKAN module in this scenario as well: +.. prompt:: bash $ + mkdir myproject && cd myproject ddev config --auto ddev get https://github.com/GetDKAN/dkan-ddev-addon/archive/refs/heads/main.tar.gz @@ -48,8 +62,10 @@ And you can substitute the local dev DKAN module in this scenario as well: cd dkan git checkout my_feature_branch ddev dkan-site-install - # Work on the module.... - ddev dkan-module-test-cypress - # Work on the module.... + +Work on the module.... + +.. prompt:: bash $ + ddev dkan-module-test-cypress - # etc. + diff --git a/docs/testing-project.md b/docs/testing-project.rst similarity index 88% rename from docs/testing-project.md rename to docs/testing-project.rst index ff097b8..083d720 100644 --- a/docs/testing-project.md +++ b/docs/testing-project.rst @@ -1,6 +1,8 @@ -# Testing your local development project. +Testing your local development project. +======================================= -## How to set up your tests +How to set up your tests +------------------------ Or: An Opinionated Test Runner @@ -9,10 +11,14 @@ project so it can be tested in a predictable manner. If your project layout is correct, you can use these commands to run tests: +.. prompt:: bash $ + ddev project-test-phpunit ddev project-test-cypress -### PHPUnit setup + +PHPUnit setup +^^^^^^^^^^^^^ Your site needs a `phpunit.xml` configuration file for PHPUnit. @@ -24,6 +30,8 @@ PHPUnit will be run within this directory. You can put this file where it belongs by copying it: +.. prompt:: bash $ + cp .ddev/misc/phpunit.xml docroot/modules/custom This PHPUnit configuration file defines a test suite called Custom Test Suite. @@ -31,10 +39,14 @@ This suite covers all the tests in the custom modules directory. Run the tests with this command: +.. prompt:: bash $ + ddev project-test-phpunit You can add arguments as if you were running the PHPUnit executable: +.. prompt:: bash $ + ddev project-test-phpunit --filter SpecialTest::testSpecialMethod If you find that your project needs more specialized setup than this @@ -46,7 +58,8 @@ fields at the top. Be sure and document the use of this command in your project's `README.md` :-) -### Cypress setup +Cypress setup +^^^^^^^^^^^^^ Currently, the project Cypress test runner assumes that you have Cypress installed locally on your machine. The runner will run this version of @@ -54,6 +67,8 @@ Cypress against the DDev environment. Begin by installing Cypress. For DKAN, we require Cypress 8.7. +.. prompt:: bash $ + npm install --location=global cypress@8.7 npx cypress verify npx cypress info @@ -61,6 +76,8 @@ Begin by installing Cypress. For DKAN, we require Cypress 8.7. Next you'll need to set up the site itself, so there is a live site in DDev to test against. +.. prompt:: bash $ + ddev dkan-init ddev dkan-site-install @@ -72,6 +89,8 @@ though this may change. Now you can run the tests: +.. prompt:: bash $ + ddev project-test-cypress Much like the PHPUnit command, if you find that your project needs more diff --git a/doxygen-build/Dockerfile b/doxygen-build/Dockerfile deleted file mode 100644 index 7e0fb0e..0000000 --- a/doxygen-build/Dockerfile +++ /dev/null @@ -1,12 +0,0 @@ -#ddev-generated - -ARG BASE_IMAGE -FROM $BASE_IMAGE - -RUN apt-get update -y && apt-get upgrade -y \ - && DEBIAN_FRONTEND=noninteractive apt-get install -y doxygen \ - && apt-get clean && apt-get autoclean \ - && rm -rf /var/lib/apt/lists/* - -WORKDIR /data -VOLUME ["/data"] diff --git a/install.yaml b/install.yaml index 67a2372..ab0d0c0 100644 --- a/install.yaml +++ b/install.yaml @@ -52,7 +52,6 @@ pre_install_actions: project_files: - config.dkan.yaml - commands/cypress/cypress - - commands/doxygen/dkan-docs - commands/host/dkan-demo - commands/host/dkan-frontend-test-cypress - commands/host/dkan-init @@ -68,8 +67,6 @@ project_files: - commands/web/dkan-test-phpunit - commands/web/dkan-test-users - commands/web/project-test-phpunit - - docker-compose.doxygen.yaml - - doxygen-build/Dockerfile - misc/docker-compose.cypress.yaml - misc/phpunit.xml - misc/settings.dkan.php diff --git a/tests/doxygen.bats b/tests/doxygen.bats deleted file mode 100644 index 87d2d66..0000000 --- a/tests/doxygen.bats +++ /dev/null @@ -1,44 +0,0 @@ -setup() { - set -eu -o pipefail - - load 'test_helper/bats-support/load' - load 'test_helper/bats-assert/load' - - export DIR="$( cd "$( dirname "$BATS_TEST_FILENAME" )" >/dev/null 2>&1 && pwd )/.." - export PROJNAME=test-dkan-ddev-addon - export TESTDIR=~/tmp/$PROJNAME - mkdir -p $TESTDIR - export DDEV_NON_INTERACTIVE=true - ddev delete -Oy ${PROJNAME} || true - cd "${TESTDIR}" - ddev config --project-name=${PROJNAME} - ddev get ${DIR} - ddev restart - ddev dkan-init --force -} - -teardown() { - set -eu -o pipefail - echo "teardown..." - cd ${TESTDIR} || ( printf "unable to cd to ${TESTDIR}\n" && exit 1 ) - ddev delete -Oy ${PROJNAME} - # chown the test dir to current user. - [ "${TESTDIR}" != "" ] && sudo chown -R $USER: ${TESTDIR} - [ "${TESTDIR}" != "" ] && rm -rf ${TESTDIR} -} - -@test "doxygen service and command" { - set -eu -o pipefail - cd ${TESTDIR} - - run ddev exec -s doxygen exit 0 - assert_success - - run ddev dkan-docs --help - assert_output --partial "Generate documentation for the DKAN module" - assert_success - - run ddev dkan-docs - assert_output --partial "Documentation is now available at" - assert_success -}