diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 4dacffd0850..1cdf78ee3e0 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -27,7 +27,7 @@ jobs: pip install -r requirements/docs.txt - name: Build docs - run: mkdocs build + run: mkdocs build --strict - name: Publish docs run: mkdocs gh-deploy diff --git a/docs/atomic-structure.md b/docs/atomic-structure.md index c6b9d4b89cf..579edd07e43 100644 --- a/docs/atomic-structure.md +++ b/docs/atomic-structure.md @@ -11,7 +11,7 @@ If a component doesn’t have user interactions or require styling, then it won’t have an associated JS and/or Less file. Components that are available for adding to a Wagtail page also require some Python programming—see the -[creating and editing components](../editing-components/) page for details. +[creating and editing components](editing-components.md) page for details. We compose our atomic components as follows: diff --git a/docs/contributing-docs.md b/docs/contributing-docs.md index 3aa1b0ecf8d..b2773af7cdf 100644 --- a/docs/contributing-docs.md +++ b/docs/contributing-docs.md @@ -44,7 +44,7 @@ nav: ## Running the docs locally With a -[stand-alone Python virtualenv for consumerfinance.gov](../installation/#set-up-a-local-python-environment-optional): +[stand-alone Python virtualenv for consumerfinance.gov](installation.md#set-up-a-local-python-environment-optional): ```bash pyenv activate consumerfinance.gov @@ -59,7 +59,7 @@ Once running, they are accessible at http://localhost:8888. Every time a PR is merged to main, GitHub Actions will build and deploy the documentation to https://cfpb.github.io/consumerfinance.gov/. -See [How we use GitHub Actions](../github-actions/) for more info. +See [How we use GitHub Actions](github-actions.md) for more info. If you would like to deploy to a fork of consumerfinance.gov owned by another user you can provide the `-r` argument: diff --git a/docs/editing-components.md b/docs/editing-components.md index edcba090a74..1bbabac1ef2 100644 --- a/docs/editing-components.md +++ b/docs/editing-components.md @@ -46,7 +46,7 @@ Blocks are implemented via several different bits of code: 1. [(Optionally) adding some JavaScript for adding advanced behavior](#adding-javascript) Before you dive in further, -[check out the Notes on Atomic Design page](../atomic-structure/) +[check out the Notes on Atomic Design page](atomic-structure.md) and familiarize yourself with our basic concepts of atoms, molecules, and organisms. @@ -179,7 +179,7 @@ but in the footer on others) on the sidebar tab. ### The front end Before diving into the front-end code, a reminder to -visit the [Notes on Atomic Design](../atomic-structure/) page +visit the [Notes on Atomic Design](atomic-structure.md) page to learn about how we conceive of components in a hierarchy of atoms, molecules, and organisms. @@ -268,7 +268,7 @@ you can add it by creating a new Also be sure that new component designs have gone through our internal approval process before adding them to the project. -If you're working on a general-purpose [atomic component](../atomic-structure/) +If you're working on a general-purpose [atomic component](atomic-structure.md) for site-wide use, this file should live in `cfgov/unprocessed/css//`. (Choose the deepest folder according to the atomic rank of the component.) @@ -311,7 +311,7 @@ class RelatedContent(blocks.StructBlock): (The `related-content.js` file would need to be placed in `cfgov/unprocessed/js/molecules/`; -see [Notes on Atomic Design](../atomic-structure/).) +see [Notes on Atomic Design](atomic-structure.md).) This will load the `related-content.js` script on any page that includes the `RelatedContent` molecule in one of its StreamFields. @@ -320,7 +320,7 @@ that includes the `RelatedContent` molecule in one of its StreamFields. ### Creating a new component -1. Review the [Notes on Atomic Design](../atomic-structure/) page. +1. Review the [Notes on Atomic Design](atomic-structure.md) page. 1. Add each of the parts mentioned above: 1. [Create the Python class](#the-python-class) 1. [Add the class to a StreamField](#adding-it-to-a-streamfield) @@ -457,4 +457,4 @@ experience a gap in the data that is being manually replaced. --- For more details on both kinds of migrations, -see [the Wagtail Migrations page](../migrations/). +see [the Wagtail Migrations page](migrations.md). diff --git a/docs/github-actions.md b/docs/github-actions.md index b3bd78b67d3..0c67fb528cc 100644 --- a/docs/github-actions.md +++ b/docs/github-actions.md @@ -28,6 +28,6 @@ Our workflows are defined in our [`.github/workflows`](https://github.com/cfpb/c ## An extra task for satellite repositories -For our [satellite apps](../related-projects/#satellite-apps), we use GitHub Actions (or Travis, if a repo hasn't been migrated to Actions yet) to build and attach a deployment wheel file to every release. +For our [satellite apps](related-projects.md#satellite-apps), we use GitHub Actions (or Travis, if a repo hasn't been migrated to Actions yet) to build and attach a deployment wheel file to every release. An example is the `.whl` file on [this release of the retirement app](https://github.com/cfpb/retirement/releases/tag/0.7.6). diff --git a/docs/installation.md b/docs/installation.md index 834c51579f6..d9a9260bede 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -28,7 +28,7 @@ The Wagtail admin area will be available at , which you can log into with the credentials `admin`/`admin`. Please see -our [running consumerfinance.gov](/running/) documentation +our [running consumerfinance.gov](running-virtualenv.md) documentation for next steps. There are also optional steps described below, as well as @@ -69,7 +69,7 @@ cp -a .env_SAMPLE .env ### Set up a local Python environment (optional) For running our -[Python unit tests, linting, etc](/python-unit-tests/) +[Python unit tests, linting, etc](python-unit-tests.md) outside of the Docker container, we rely on a local Python environment. !!! note @@ -185,7 +185,7 @@ to assist developers with linting without thinking. We have a single script that will install our frontend dependencies for both building and -[unit testing/linting/etc](/javascript-unit-tests/): +[unit testing/linting/etc](javascript-unit-tests.md): ```sh ./frontend.sh @@ -279,7 +279,7 @@ CFGOV_PROD_DB_LOCATION=http://(rest of the URL) ./refresh-data.sh /path/to/dump.sql.gz ``` -This automatically [(re)builds the Elasticsearch index](/search/#building-the-index), +This automatically [(re)builds the Elasticsearch index](page-search.md#building-the-index), unless you run the `refresh-data.sh` script with the `--noindex` flag. ## Alternative setups diff --git a/docs/javascript-unit-tests.md b/docs/javascript-unit-tests.md index d71293e4741..76b72364156 100644 --- a/docs/javascript-unit-tests.md +++ b/docs/javascript-unit-tests.md @@ -143,7 +143,7 @@ the structure of the project JavaScript in When considering exactly where to place JavaScript in these directories, it might be helpful to review the documentation about -[atomic components in consumerfinance.gov](../atomic-structure). +[atomic components in consumerfinance.gov](atomic-structure.md). JavaScript corresponding to atomic elements should go into the appropriate subfolder for the type of element being implemented. In our case, `sample.js` and `sample-spec.js` don’t relate to atomic elements, @@ -586,7 +586,7 @@ and assigns the component node to the `notificationElem` variable, and the tests would have to reconcile into a complete, finished chunk of markup. For now, just be aware of this when - [editing a Wagtail component that includes JavaScript](../editing-components/). + [editing a Wagtail component that includes JavaScript](editing-components.md). Further down, here are some of the tests that cover the `_setType` function (by way of the `setTypeAndContent` function that @@ -642,4 +642,4 @@ Testing user interaction with simulated pointer events, keystrokes, or form submissions is best handled via browser tests, not unit tests. User interaction in a unit test could falsely pass if the component wasn’t visible on the page, for instance. -[Read more about how we run browser tests with Cypress.](../functional-testing/) +[Read more about how we run browser tests with Cypress.](functional-testing.md) diff --git a/docs/migrations.md b/docs/migrations.md index b3232995727..2ad37c25cf0 100644 --- a/docs/migrations.md +++ b/docs/migrations.md @@ -105,7 +105,7 @@ and the time that your PR is ready for merging, you will have to update your branch as normal to be current with main and then re-create your migration. Also note that our -[back-end tests that run in GitHub Actions](../github-actions/) +[back-end tests that run in GitHub Actions](github-actions.md) will fail if a required schema migration is missing or if migrations are in conflict with one another. diff --git a/docs/page-search.md b/docs/page-search.md index 4589cc91564..5210ba33b5d 100644 --- a/docs/page-search.md +++ b/docs/page-search.md @@ -15,7 +15,7 @@ For page searches on consumerfinance.gov, we use Elasticsearch and the [django-o ## Indexing -For any of our Django apps that need to implement search for their Django models or [Wagtail page types](../wagtail-pages/), we include a `documents.py` file that defines the Elasticsearch documents that will [map the model or page to the Elasticsearch index](https://django-opensearch-dsl.readthedocs.io/en/latest/getting_started/#create-document-classes). +For any of our Django apps that need to implement search for their Django models or [Wagtail page types](wagtail-pages.md), we include a `documents.py` file that defines the Elasticsearch documents that will [map the model or page to the Elasticsearch index](https://django-opensearch-dsl.readthedocs.io/en/latest/getting_started/#create-document-classes). The `Document` class includes three things: diff --git a/docs/python-unit-tests.md b/docs/python-unit-tests.md index a6d14aa2ed1..8e7603ea788 100755 --- a/docs/python-unit-tests.md +++ b/docs/python-unit-tests.md @@ -35,9 +35,9 @@ for additional details on its functionality. ## Prerequisites If you have set up -[a standalone installation of consumerfinance.gov](/installation/#install-system-level-requirements), +[a standalone installation of consumerfinance.gov](installation.md#install-system-level-requirements), you'll need to -[activate your virtual environment](/running-virtualenv/#3-launch-site) +[activate your virtual environment](running-virtualenv.md#3-launch-site) before running the tests: ```sh @@ -53,7 +53,7 @@ pip install tox ``` If you have set up -[a Docker-based installation of consumerfinance.gov](/installation/#docker-based-installation), +[a Docker-based installation of consumerfinance.gov](installation.md#docker-based-installation), you can run the tests there by [accessing the Python container's shell](http://localhost:8888/running-docker/#access-a-containers-shell): @@ -188,7 +188,7 @@ TEST_RUNNER=core.testutils.runners.StdoutCapturingTestRunner tox -e unittest ``` This test runner is enabled when tests are run automatically on -[GitHub Actions](../github-actions/), +[GitHub Actions](github-actions.md), but is not used by default when running tests locally. ## GovDelivery diff --git a/docs/related-projects.md b/docs/related-projects.md index 6361ed47821..0a3aa810add 100644 --- a/docs/related-projects.md +++ b/docs/related-projects.md @@ -48,7 +48,7 @@ contains the CFPB development guidelines used on these projects. Developers working on changes to satellite apps or other Python packages often want or need to test their work as part of the larger consumerfinance.gov project. -The standard [installation](../installation/) process for consumerfinance.gov +The standard [installation](installation.md) process for consumerfinance.gov includes whatever versions of these packages are specified in project [requirements files](https://github.com/cfpb/consumerfinance.gov/blob/main/requirements/libraries.txt). Developers may want to temporarily or permanently replace those with a local @@ -104,13 +104,13 @@ requirements files: ``` Re-running the full virtual environment -[setup script](../installation/#run-the-setup-script) +[setup script](installation.md#run-the-setup-script) will do the same thing. ### Using Docker Working on Python packages requires a different approach when running -consumerfinance.gov locally with [its Docker setup](../running-docker/). +consumerfinance.gov locally with [its Docker setup](running-docker.md). This is because while your local `consumerfinance.gov` directory is exposed to the container, sibling directories or other locations where you might clone other repositories are not. diff --git a/docs/running-docker.md b/docs/running-docker.md index ce41092f288..c9999a0733a 100644 --- a/docs/running-docker.md +++ b/docs/running-docker.md @@ -1,7 +1,7 @@ # Running in Docker First, follow -[the Docker installation instructions](../installation/#docker-based-installation) +[the Docker installation instructions](installation.md#docker-based-installation) to setup your Docker environment and create the project Docker containers. We use [`docker-compose`](https://docs.docker.com/compose/reference/overview/) @@ -82,7 +82,7 @@ docker-compose up --build python ## Work on satellite apps -See [“Using Docker” on the Related Projects page](../related-projects/#using-docker). +See [“Using Docker” on the Related Projects page](related-projects.md#using-docker). ## Attach for debugging diff --git a/docs/running-virtualenv.md b/docs/running-virtualenv.md index 233c2cd252d..f4ebd410c9b 100644 --- a/docs/running-virtualenv.md +++ b/docs/running-virtualenv.md @@ -1,7 +1,7 @@ # Running in a Virtual Environment First, follow -[the standalone installation instructions](../installation/#stand-alone-installation) +[the standalone installation instructions](installation.md#stand-alone-installation) to create your virtual environment, install required dependencies, and run the setup scripts. @@ -137,7 +137,7 @@ yarn test # Run both ### Reinstalling the virtual environment To remove an existing virtual environment for -[a reinstall of consumerfinance.gov](../installation/#stand-alone-installation), +[a reinstall of consumerfinance.gov](installation.md#stand-alone-installation), first deactivate the virtual environment if it is active: ```bash @@ -151,5 +151,5 @@ rmvirtualenv consumerfinance.gov ``` After this, you may follow -[the installation instructions](installation/#stand-alone-installation) +[the installation instructions](installation.md#stand-alone-installation) again. diff --git a/mkdocs.yml b/mkdocs.yml index b00e37c8b77..9f30cef3ace 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -57,3 +57,8 @@ markdown_extensions: - tables - toc: permalink: '¶' + +validation: + omitted_files: warn + absolute_links: warn + unrecognized_links: warn