From 73481173f39ca26fa4703a7c4acc19ea6e6ccda1 Mon Sep 17 00:00:00 2001 From: Janette Day Date: Fri, 27 Oct 2023 13:26:33 -0500 Subject: [PATCH] update-docs-1 (#34) --- .gitignore | 1 + README.md | 8 +++---- config.dkan.yaml | 2 +- docker-compose.doxygen.yaml | 32 ------------------------- docs/_config.yml | 2 +- docs/docs.md | 9 ------- docs/getting-started.md | 10 ++++---- docs/index.md | 6 ++--- docs/testing-debug-phpunit.md | 28 +++++++++++----------- docs/testing-project.md | 4 ++-- doxygen-build/Dockerfile | 12 ---------- install.yaml | 4 +--- tests/doxygen.bats | 44 ----------------------------------- 13 files changed, 32 insertions(+), 130 deletions(-) delete mode 100644 docker-compose.doxygen.yaml delete mode 100644 docs/docs.md delete mode 100644 doxygen-build/Dockerfile delete mode 100644 tests/doxygen.bats diff --git a/.gitignore b/.gitignore index 60607d7..6ca3c4e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ .idea +.vscode tests/bats tests/test_helper diff --git a/README.md b/README.md index 773d1c4..2322f1d 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,13 @@ -[![tests](https://github.com/getdkan/dkan-ddev-addon/actions/workflows/tests.yml/badge.svg)](https://github.com/drud/ddev-dkan-ddev-addon/actions/workflows/tests.yml) ![project is maintained](https://img.shields.io/maintenance/yes/2023.svg) +[![tests](https://github.com/getdkan/ddev-dkan/actions/workflows/tests.yml/badge.svg)](https://github.com/drud/ddev-dkan-ddev-addon/actions/workflows/tests.yml) ![project is maintained](https://img.shields.io/maintenance/yes/2023.svg) -## What is dkan-ddev-addon? +## What is ddev-dkan? -DKAN DDev Add-on provides commands and config for development of +DDEV-DKAN add-on provides commands and config for development of DKAN itself and DKAN-enabled Drupal sites in a local docker environment. ## Documentation -Documentation lives in Github Pages: https://getdkan.github.io/dkan-ddev-addon/ +Documentation lives in Github Pages: https://getdkan.github.io/ddev-dkan/ ## Testing diff --git a/config.dkan.yaml b/config.dkan.yaml index 141f10f..5ec386a 100644 --- a/config.dkan.yaml +++ b/config.dkan.yaml @@ -2,7 +2,7 @@ type: drupal9 docroot: docroot -php_version: "8.0" +php_version: "8.1" webserver_type: apache-fpm router_http_port: "80" router_https_port: "443" 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/_config.yml b/docs/_config.yml index c741881..a25eb13 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1 +1 @@ -theme: jekyll-theme-slate \ No newline at end of file +theme: minima 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/getting-started.md b/docs/getting-started.md index 272417b..70e3ca8 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,4 +1,4 @@ -# Getting started with DKAN DDev Addon +# Getting started with DDEV-DKAN add-on ## Start a new DKAN site @@ -6,7 +6,7 @@ First, make a directory for your project. mkdir my-project && cd my-project -Give DDev just enough configuration to get started. +Give DDEV just enough configuration to get started. ddev config --auto @@ -37,7 +37,7 @@ standard tools to log in: 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: ddev dkan-init --help @@ -70,7 +70,7 @@ use that repo as the getdkan/dkan package. ## 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 @@ -86,7 +86,7 @@ Now that you have all the dependencies, you can build the frontend: ddev dkan-frontend-build Currently this command essentially calls `npm run build` within the web container -of DDev. +of DDEV. ## Additional Commands diff --git a/docs/index.md b/docs/index.md index ccaa9b0..82184c3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,7 @@ -# DKAN DDev Addon +# DDEV-DKAN add-on -The DKAN DDEv Addon provides configuration and specialized commands for dealing -with a DKAN Drupal project in the DDEv environment. +The DDEV-DKAN 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: diff --git a/docs/testing-debug-phpunit.md b/docs/testing-debug-phpunit.md index 237a98c..7b42235 100644 --- a/docs/testing-debug-phpunit.md +++ b/docs/testing-debug-phpunit.md @@ -1,6 +1,6 @@ -# 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 +This documentation is specific to using the DKAN DDEV addon, but can be generalized for many other use-cases. Currently, we're only going to talk about using PHPStorm. Do you have @@ -8,7 +8,7 @@ instructions for another IDE? Make a pull request. :-) ## Goals -We want to be able to use our DDev environment to do step-debugging for PHPUnit-based tests, using PHPStorm. +We want to be able to use our DDEV environment to do step-debugging for PHPUnit-based tests, using PHPStorm. There are three main moving parts in this process: - The remote PHP interpreter. @@ -18,13 +18,13 @@ There are three main moving parts in this process: ## 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. +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](https://plugins.jetbrains.com/plugin/18813-ddev-integration). 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. +DDEV environments, among other minor luxuries. ## 2. Configure the PHPUnit framework @@ -35,9 +35,9 @@ test coverage reporting. - Select PHPStorm -> Preferences. - Choose the PHP -> Test Frameworks tab. - Click +. -- Add 'PHPUnit by remote interpreter'. The remote interpreter is our DDev environment. -- 'PHP interpreter' should be DDev. -- 'Path mappings' should be set up by the DDev integration plugin. +- Add 'PHPUnit by remote interpreter'. The remote interpreter is our DDEV environment. +- 'PHP interpreter' should be DDEV. +- 'Path mappings' should be set up by the DDEV integration plugin. - Under 'PHPUnit Library', select 'Path to phpunit.phar' and use the path `vendor/phpunit/phpunit/phpunit` - Click the reload icon next to the path and see if PHPStorm finds the binary. If it doesn't maybe you haven't run `ddev composer install` yet? - Leave the default configuration and bootstrap file fields empty. @@ -60,7 +60,7 @@ Now that you know where your DKAN module is located, you can create the Run/Debu - From the menu, select Run -> Edit Configurations... - Click +. - Select 'PHPUnit' as the basis of our runner. -- Give it a good name. I decided on 'DDev PHPUnit', because I lack creativity. +- Give it a good name. I decided on 'DDEV PHPUnit', because I lack creativity. - Under 'Test runner', choose 'Defined in the configuration file'. - Check the 'Use alternative configuration file' box, and enter the path to the configuration file. This is the PHPUnit configuration file in the DKAN module. As mentioned above, it could be in a few different places. On my Mac, @@ -76,7 +76,7 @@ This is the end of the easy part. Now comes the two complicated things: 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: +differ for every site. Therefore, we've added a DDEV command for it: ddev dkan-get-env-for-phpunit @@ -110,8 +110,8 @@ Now we can fill out the 'Before launch' part of the Run/Debug configuration. - Choose 'Run External Tool'. This will show you another list. - Click +. - You can give your new external tool a name and description. I decided on 'create users'. -- 'Program' is the path to DDev. In my case, it's `/usr/local/bin/ddev`. If you want to find yours, you can say `which ddev` at the command line. -- 'Arguments' is the DDev command we want to run. Enter `dkan-test-users`. +- 'Program' is the path to DDEV. In my case, it's `/usr/local/bin/ddev`. If you want to find yours, you can say `which ddev` at the command line. +- 'Arguments' is the DDEV command we want to run. Enter `dkan-test-users`. - 'Working directory' should be `$ProjectFileDir$`. - Click 'OK' and 'OK' again on the external tools window. - Now you can 'Apply' and 'OK' on the Run/Debug configuration form. @@ -128,7 +128,7 @@ 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/) -- Tell DDev to use XDebug: `ddev xdebug on`. +- 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) diff --git a/docs/testing-project.md b/docs/testing-project.md index ff097b8..22983ae 100644 --- a/docs/testing-project.md +++ b/docs/testing-project.md @@ -50,7 +50,7 @@ Be sure and document the use of this command in your project's `README.md` :-) Currently, the project Cypress test runner assumes that you have Cypress installed locally on your machine. The runner will run this version of -Cypress against the DDev environment. +Cypress against the DDEV environment. Begin by installing Cypress. For DKAN, we require Cypress 8.7. @@ -59,7 +59,7 @@ Begin by installing Cypress. For DKAN, we require Cypress 8.7. npx cypress info Next you'll need to set up the site itself, so there is a live site in -DDev to test against. +DDEV to test against. ddev dkan-init ddev dkan-site-install 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..573bdc8 100644 --- a/install.yaml +++ b/install.yaml @@ -1,4 +1,4 @@ -name: dkan-ddev-addon +name: ddev-dkan # pre_install_actions - list of actions to run before installing the addon. # Examples would be removing an extraneous docker volume, @@ -68,8 +68,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 -}