diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index c5edad3b2d..a9b35cc791 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -19,8 +19,8 @@ jobs: pip install -q -r requirements.txt sudo snap install --edge vale - - name: Run tests with make test - run: make test + - name: Build HTML + run: make html - name: Run vale run: | @@ -28,3 +28,6 @@ jobs: cp -r ./Microsoft/Microsoft ./styles VALEFILES=$(find -L ./docs/ -type d \( -path "./docs/plone.restapi/lib/*" -o -path "./docs/plone.restapi/performance/*" \) -prune -false -o -type f -name "*.md" -print) vale --no-exit $VALEFILES + + - name: Check for broken links + run: make linkcheck diff --git a/Makefile b/Makefile index 492f479d40..b4b0ac5338 100644 --- a/Makefile +++ b/Makefile @@ -189,7 +189,7 @@ changes: deps .PHONY: linkcheck linkcheck: deps ## Run linkcheck - cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck -W $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/ ." @echo diff --git a/docs/backend/upgrading/version-specific-migration/upgrade-to-52.md b/docs/backend/upgrading/version-specific-migration/upgrade-to-52.md index be670bb57d..b326ba42ed 100644 --- a/docs/backend/upgrading/version-specific-migration/upgrade-to-52.md +++ b/docs/backend/upgrading/version-specific-migration/upgrade-to-52.md @@ -162,7 +162,7 @@ Nothing changes. You can now use a RESTful hypermedia API for Plone to build modern JavaScript frontends on top of Plone. Also, the REST API can be used to import or export data. -See https://plonerestapi.readthedocs.io/en/latest/ for details. +See {doc}`/plone.restapi/docs/source/index` for details. ### New navigation with dropdown diff --git a/docs/backend/upgrading/version-specific-migration/upgrade-to-60.md b/docs/backend/upgrading/version-specific-migration/upgrade-to-60.md index acbd9c6b43..3df55533a7 100644 --- a/docs/backend/upgrading/version-specific-migration/upgrade-to-60.md +++ b/docs/backend/upgrading/version-specific-migration/upgrade-to-60.md @@ -148,7 +148,7 @@ Plone 6.0 means we move from Zope 4 to 5. This drops support for Python 2.7, drops `ZServer`, and removes deprecated code. ```{seealso} -[Zope 5.0a1](https://zope.readthedocs.io/en/latest/changes.html#a1-2020-02-28) +[Zope 5.0a1](https://zope.readthedocs.io/en/5.x/changes.html#a1-2020-02-28) ``` Some imports may need to change. diff --git a/docs/classic-ui/templates.md b/docs/classic-ui/templates.md index 81cf2df2f8..550b07ec84 100644 --- a/docs/classic-ui/templates.md +++ b/docs/classic-ui/templates.md @@ -14,7 +14,7 @@ myst: Page Templates are the primary way to generate HTML output in Plone Classic UI. They are HTML files enhanced with special attributes written in TAL (Template Attribute Language), TALES (TAL Expression Syntax), and METAL (Macro Expansion for TAL). -Plone uses [Chameleon](https://chameleon.readthedocs.io/) as its template engine, integrated through the Zope framework. +Plone uses [Chameleon](https://chameleon.readthedocs.io/en/latest/) as its template engine, integrated through the Zope framework. Chameleon is a fast HTML/XML template engine that implements the ZPT (Zope Page Templates) specification with additional features. @@ -970,5 +970,5 @@ import pdb; pdb.set_trace() - {doc}`views` - {doc}`viewlets` - {doc}`template-global-variables` -- [Chameleon documentation](https://chameleon.readthedocs.io/) +- [Chameleon documentation](https://chameleon.readthedocs.io/en/latest/) - {doc}`training-2023:mastering-plone-5/zpt` diff --git a/docs/conf.py b/docs/conf.py index e1619ddedc..333cd42f9c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -93,21 +93,23 @@ r"https://classic.demo.plone.org/en/demo/an-image.jpg/@@images-test#srcset", r"https://javascript.plainenglish.io/you-dont-need-lodash-how-i-gave-up-lodash-693c8b96a07c", # Ignore pages that are rate limited or otherwise blocked + r"https://codesandbox.io/", + r"https://docutils.sourceforge.io/", + r"https://hosted.weblate.org/", + r"https://medium.com", + r"https://pastanaga.io", r"https://stackoverflow.com", + r"https://v5.reactrouter.com", + r"https://www.merriam-webster.com/", r"https://www.npmjs.com/", - r"https://hosted.weblate.org/", # Ignore github.com pages with anchors r"https://github.com/.*#.*", - # Ignore rate limiting by github.com + # Ignore redirects and rate limiting by github.com r"https://github.com/plone/volto/issues", r"https://github.com/plone/volto/pull", # Ignore other specific anchors - r"https://coveralls.io/repos/github/plone/plone.restapi/badge.svg\?branch=main", # plone.restapi - r"https://hosted.weblate.org/accounts/profile/#notifications", r"https://browsersl.ist/#", # volto - # Ignore unreliable sites - r"https://.*.gnu.org/", - # fluke where Sphinx interprets this as a URL + # fluke where Sphinx MyST linkify extension interprets this as a URL r"http://z3c.pt", ] linkcheck_allowed_redirects = { diff --git a/docs/contributing/documentation/authors.md b/docs/contributing/documentation/authors.md index 64afed2b9b..565b0f8429 100644 --- a/docs/contributing/documentation/authors.md +++ b/docs/contributing/documentation/authors.md @@ -121,7 +121,7 @@ make vale VALEOPTS="--minAlertLevel='warning'" VALEFILES="docs/index.md" The command `make vale` automatically installs Vale into your Python virtual environment—which is also created via any documentation `Makefile` commands—when you invoke it for the first time. -Vale has [integrations](https://vale.sh/docs/) with various IDEs. +Vale has [integrations](https://docs.vale.sh/) with various IDEs. Integration might require installing Vale using operating system's package manager. - [JetBrains](https://plugins.jetbrains.com/plugin/19613-vale-cli/docs) @@ -357,7 +357,7 @@ The Plone Documentation Team adopted additional guidelines. The reviewer can't give targeted feedback for a single sentence when there are multiple sentences on one line. - When a single sentence is broken across multiple lines, the reviewer may not know that they can submit [one suggestion for multiple lines](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request#adding-comments-to-a-pull-request). + When a single sentence is broken across multiple lines, the reviewer may not know that they can submit [one suggestion for multiple lines](https://docs.github.com/en/pull-requests/how-tos/review-pull-requests/commenting-on-a-pull-request#adding-comments-to-a-pull-request). Instead, they either make a comment or a single suggestion leaving the author to manually edit the lines. This in turn deprives you of the easy option to commit the suggestion to the pull request by a single click of a button in the GitHub user interface. diff --git a/docs/contributing/documentation/myst-reference.md b/docs/contributing/documentation/myst-reference.md index dc9372d566..8672fb799c 100644 --- a/docs/contributing/documentation/myst-reference.md +++ b/docs/contributing/documentation/myst-reference.md @@ -310,7 +310,7 @@ For an in depth discussion of privacy issues, see [How to embed YouTube videos w You can use [Mermaid](https://mermaid.js.org/) and its Sphinx extension [`sphinxcontrib.mermaid`](https://pypi.org/project/sphinxcontrib-mermaid/) to render graphs in your documents, including general flowcharts, sequence diagrams, and Gantt charts. -You can use the [Mermaid Playground](https://www.mermaidchart.com/play) to compose Mermaid markup and preview a live diagram. +You can use the [Mermaid Playground](https://mermaid.ai/live/edit) to compose Mermaid markup and preview a live diagram. ````{example} ```{mermaid} diff --git a/docs/contributing/first-time.md b/docs/contributing/first-time.md index 3de4975616..2c0e0818df 100644 --- a/docs/contributing/first-time.md +++ b/docs/contributing/first-time.md @@ -227,9 +227,9 @@ You will pull code from the upstream Plone repository, push your work from your _Plone git workflow_ ```` -1. Start by [forking the project's repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) to your account through the GitHub interface. -1. [Clone your forked repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#cloning-your-forked-repository). -1. [Configure git to sync your fork with the upstream repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#configuring-git-to-sync-your-fork-with-the-upstream-repository). +1. Start by [forking the project's repository](https://docs.github.com/en/pull-requests/how-tos/work-with-forks/fork-a-repo) to your account through the GitHub interface. +1. [Clone your forked repository](https://docs.github.com/en/pull-requests/how-tos/work-with-forks/fork-a-repo#cloning-your-forked-repository). +1. [Configure git to sync your fork with the upstream repository](https://docs.github.com/en/pull-requests/how-tos/work-with-forks/fork-a-repo#configuring-git-to-sync-your-fork-with-the-upstream-repository). (write-code-label)= @@ -291,7 +291,7 @@ Once you have completed, tested, and linted your code, and created a {ref}`contr git push -u origin my-branch-name ``` -1. Visit your fork of the Plone repository on GitHub, and [**create a pull request**](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) against the development branch. +1. Visit your fork of the Plone repository on GitHub, and [**create a pull request**](https://docs.github.com/en/pull-requests/how-tos/create-pull-requests/creating-a-pull-request) against the development branch. - Make both your title and description descriptive. Reviewers look at many pull requests, and need to quickly understand the context. A lazily written phrase such as "Fixes bug" is meaningless. @@ -305,7 +305,7 @@ Once you have completed, tested, and linted your code, and created a {ref}`contr 1. **Request a review.** Identify who you should ask by either checking the history of the files you edit, or viewing the project's list of contributors for an active member. - If you have write access to the repository, [request a review](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review) from other team members. + If you have write access to the repository, [request a review](https://docs.github.com/en/pull-requests/how-tos/create-pull-requests/requesting-a-pull-request-review) from other team members. If you do not have write access, instead add a comment and mention a few active contributors of the project, tagging them with `@username`. You can find them by either checking the files' history via `git blame` or visiting the project's {guilabel}`Contributors` page on GitHub. 1. Members who subscribe to the repository will receive a notification and review your request. diff --git a/docs/glossary.md b/docs/glossary.md index 068a569027..d8372fe9bc 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -350,7 +350,7 @@ hoisting In case two dependencies have conflicting version dependencies of the same library, the hoisting will not be possible (for that conflicting dependency) and you'll see multiple instances of the same library in the bundle, or you'll see that the add-on receives its own `node_modules` folder. React - [React](https://www.reactjs.dev/) is a JavaScript library for building user interfaces. + [React](https://reactjs.dev/) is a JavaScript library for building user interfaces. Volto, the frontend for Plone 6, uses React. Sphinx diff --git a/docs/i18n-l10n/use-an-external-translation-service.md b/docs/i18n-l10n/use-an-external-translation-service.md index cad7386680..1398cd08f4 100644 --- a/docs/i18n-l10n/use-an-external-translation-service.md +++ b/docs/i18n-l10n/use-an-external-translation-service.md @@ -26,7 +26,7 @@ When you click this icon, it invokes the Google Cloud Translation API, and the t ```{note} The usage of Google Cloud Translation API may create extra cost for the site administrator. -See [Cloud Translation pricing](https://cloud.google.com/translate/pricing) for details. +See [Cloud Translation pricing](https://cloud.google.com/products/translate/pricing) for details. ```