Plone 6 docs (#3001)

* WIP on making something usable for sphinx * Add index files, to be used with spinx * Change cheatsheet to MyST, improve the main index * Make links into a bulleted list * Add MyST link examples and a seealso to documentation's MyST cheat sheet * First draft of contributing with Volto submodules. Move existing "Managing contributions on GitHub" section after "Contributor Roles" section * remove polluted .md files having which are not in docs/ * Fix all broken links and redirects, except: - volto/upgrade-guide/index.md:283: [broken] https://github.com/kitconcept/plone.volto/pull/29: 404 Client Error: Not Found for url: https://github.com/kitconcept/plone.volto/pull/29 - volto/addons/i18n.md:15: [broken] https://github.com/plone/volto/blob/master/src/i18n.js: 404 Client Error: Not Found for url: https://github.com/plone/volto/blob/master/src/i18n.js * Add change log entry * Fix one of two broken links * Move /recipes/overridei18n.md content to /recipes/i18n.md * Docs: Add metadata * Update add-on Internationalization to current way to do * Update CHANGELOG.md * grammar and syntax fixes Co-authored-by: Steve Piercy <[email protected]> * grammar and syntax fixes Co-authored-by: Steve Piercy <[email protected]> * grammar and syntax fixes Co-authored-by: Steve Piercy <[email protected]> * mark technical terms Co-authored-by: Steve Piercy <[email protected]> * Better wording Co-authored-by: Steve Piercy <[email protected]> * Clear instructions and result Co-authored-by: Steve Piercy <[email protected]> * grammar and syntax fixes Co-authored-by: Steve Piercy <[email protected]> * Clear instructions and result Co-authored-by: Steve Piercy <[email protected]> * MySt adjustments Co-Authored-By: Steve Piercy <[email protected]> * Update i18n.md Line break * Create a new Documentation section in CHANGELOG.md * Final clean up - Consistent indent of enumerated list - Remove duplicate lines because GitHub does not allow multi-line suggestions * Deduplicate index label * Add line break * Remove bad merge conflict resolution * Fix typo * Content was moved to recipes/i18n.md * Fix bad link * Add MyST and Sphinx basic configuration * Add CHANGELOG.md entry * Add docs/_build/ to .gitignore * Remove references to files that were moved under developer-guidelines Remove comments that are obsolete Add html_meta values * Fix heading levels Add html_meta values * Align toctree elements with production Remove redundant directory listing Add html_meta values * Fix add-ons spelling Remove `./` Fix syntax highlighting and emphasis Fix broken references Add html_meta values * Fix jsx syntax highlighting Add html_meta values * Fix jsx syntax highlighting Add html_meta values * Fix reference to addons/index Add html_meta values * Fix references Add html_meta values * Merge plone6index.md into index.md Adjust references * Fix nginx syntax highlighting (conf -> nginx) Add html_meta values * Improve shell syntax highlighting and formatting Minor grammar fixes Add html_meta values * Minor grammar fixes Remove unused lexer parameter Add html_meta values * Fix download link Add html_meta values * Fix syntax highlighting Add html_meta values * Fix reference to addons/index Add html_meta values * Fix broken link to storybook Add html_meta values * Fix json highlighting (do not use ellipses or comments) Fix reference to openobjectbrowser-handler-api-label Add html_meta values * Add change log entry * Unfix "fixes" for jsx syntax highlighting * Don't use `'` in lexed code blocks. Sheesh! * Don't use `'` in lexed code blocks. Sheesh! * dedupe cheatsheet as its already in Plone docs * Revert "dedupe cheatsheet as its already in Plone docs" This reverts commit baffc8b. * Add plone to Intersphinx configuration, and update link in cheatsheet.md * Add CHANGELOG.md entry * Get version from package.json * Remove legacy folder in docs * Add typescript to toctree * Remove mkdocs config (#3070) * Remove mkdocs configuration * Use correct filename in Makefile to install requirements for standalone docs * Add CHANGELOG.md entry * Restore logos * Remove mkdocs remainings, docs-clean cleans also legacy docs envs * Move logos up to root of directory, and adjust link in README.md * Improve help comment * Update docs GitHub workflow to use Sphinx/MyST only * Add netlify target for preview of Sphinx HTML docs build * Add CHANGELOG.md entry for Netlify * Add runtime.txt to specify Python version for Netlify * Adjust Netlify build path Co-authored-by: Victor Fernandez de Alba <[email protected]> * Fix docs not referenced in any doctree. Cleanup the ones not needed * Use `orphan` field list item to build the file, but exclude from toctree omissions errors and navigation. * Add html_meta values * Use correct internal link reference * Grammar and one sentence per line * Remove obsolete links to Python Markdown extensions, now that we use MyST * Remove unnecessary and undefined variable from docs-livehtml target * Add CHANGELOG.md entry * Remove runtime.txt and instead use global setting for netlify See https://docs.netlify.com/configure-builds/environment-variables/ * Attempt to turn off some checks, set environment variable to use Python 3.8 * Remove blank configuration values. It is not possible to disable these preview builds. See https://answers.netlify.com/t/disabling-header-rules-pages-changed-redirect-rules-mixed-content-reports/46323/2 * Use netlify.toml to set PYTHON_VERSION env var instead of obscured global setting * Use MyST admonition syntax * Fix indentation of list items so that code blocks and admonitions align are within their list items Add html_meta tags * Remove optional `true` for `:sorted:` * Add html_meta values * Add CHANGELOG.md * Backport 15-alpha docs (#3066) * Changes in docs (upgrade guide) until Volto 15a3 * Upgrade Guide i18n: Make clear what's project, what add-on. @ksuess (backport #3056) * Add Widget additional information link (#2999) Add a link to widget developer recipe at the end of Widget section. I think it is import to point developer where to find information about customizing and overriding widgets. Thanks @tiberiuichim for the tip https://community.plone.org/t/using-react-currency-selector/14737 * Backport RAZZLE_ environment variable docs Add html_meta tag values for SEO See https://github.com/plone/volto/pull/3067/files#diff-00609ed769cd40cf3bc3d6fcc4431b714cb37c73cedaaea18fe9fc4c1c589597 * Backport upgrade guide for #2992 (Lazy load draftJS) * Backport Richsettings docs of #2992 * Backport docs for #3067 (ADDONS var) * Update changelog to latest Co-authored-by: Arky <[email protected]> Co-authored-by: Steve Piercy <[email protected]> Co-authored-by: Victor Fernandez de Alba <[email protected]> Co-authored-by: Steve Piercy <[email protected]> Co-authored-by: nileshgulia1 <[email protected]> Co-authored-by: ksuess <[email protected]> Co-authored-by: Arky <[email protected]>
plone · Feb 20, 2022 · 59d5af4 · 59d5af4
1 parent 265171d
commit 59d5af4
Show file tree

Hide file tree

Showing 123 changed files with 3,266 additions and 1,038 deletions.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -4,14 +4,14 @@ about: Create a report to help us improve Volto
 title: ''
 labels: '01 type: bug'
 assignees: ''
-
 ---
 
 **Describe the bug**
 A clear and concise description of what the bug is.
 
 **To Reproduce**
 Steps to reproduce the behavior:
+
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
@@ -24,11 +24,12 @@ A clear and concise description of what you expected to happen.
 If applicable, add screenshots to help explain your problem.
 
 **Software (please complete the following information):**
- - OS: [e.g. iOS]
- - Browser [e.g. chrome, safari]
- - Volto Version [e.g. 8.5.0]
- - Plone Version [e.g. 5.2.2] 
- - Plone REST API Version [e.g. 7.0.1]
+
+- OS: [e.g. iOS]
+- Browser [e.g. chrome, safari]
+- Volto Version [e.g. 8.5.0]
+- Plone Version [e.g. 5.2.2]
+- Plone REST API Version [e.g. 7.0.1]
 
 **Additional context**
 Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -4,7 +4,6 @@ about: Suggest an idea for Volto
 title: ''
 labels: '04 type: enhancement'
 assignees: ''
-
 ---
 
 **Is your feature request related to a problem? Please describe.**

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -3,79 +3,41 @@ on:
   push:
     branches:
       - master
+    # Build pull requests
+    pull_request:
+
 jobs:
-  build:
+  docs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [16.x]
-        python-version: [3.7]
+        python-version: [3.10]
     steps:
       - uses: actions/checkout@v2
 
-      # node setup
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v1
-        with:
-          node-version: ${{ matrix.node-version }}
-
-      # node cache
-      - name: Get yarn cache directory path
-        id: yarn-cache-dir-path
-        run: echo "::set-output name=dir::$(yarn cache dir)"
-      - uses: actions/cache@v1
-        id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`)
-        with:
-          path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
-          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-yarn-
-
-      # node install
-      - run: yarn install --frozen-lockfile
-
-      # python setup
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v1
+        uses: actions/setup-python@v2
         with:
           python-version: ${{ matrix.python-version }}
 
-      # python cache
-      - uses: actions/cache@v1
+      - name: Use Python GitHub Actions cache
+        uses: actions/cache@v2
         with:
           path: ~/.cache/pip
           key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements-docs.txt') }}
           restore-keys: |
             ${{ runner.os }}-pip-
 
-      # python install
-      - run: pip install virtualenv
+      - name: Create Python virtual environment
+        run: pip install virtualenv
 
-      - name: pip install
+      - name: pip install requirements
         run: pip install -r requirements-docs.txt
 
-      # Build main documentation
-      - name: Build documentation
+      - name: Check for broken links
         working-directory: docs
-        run: mkdocs build
-
-      # Build Storybook
-      - name: Build Storybook
-        run: yarn build-storybook -o docs/build/storybook
-
-      # Deploy docs to server
-      - name: Deploy to server
-        id: deploy
-        uses: Pendect/[email protected]
-        env:
-          DEPLOY_KEY: ${{secrets.DEPLOY_KEY}}
-        with:
-          flags: '-avzr --delete'
-          options: ''
-          ssh_options: '-p ${{secrets.DEPLOY_PORT}}'
-          src: 'docs/build/'
-          dest: '${{secrets.DEPLOY_USER}}@${{secrets.DEPLOY_SERVER}}:/var/www/docs.voltocms.com'
-
+        run: make docs-linkcheckbroken
 
-      - name: Display status from deploy
-        run: echo "${{ steps.deploy.outputs.status }}"
+      - name: Build HTML documentation
+        working-directory: docs
+        run: make docs-html
diff --git a/.gitignore b/.gitignore
@@ -65,3 +65,6 @@ cypress/screenshots
 # Local environment setup
 .env
 public/critical.css
+
+# Sphinx and MyST
+docs/_build/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,6 +10,24 @@
 
 ### Internal
 
+### Documentation
+
+- (Experimental) Prepare documentation for MyST and importing into `plone/documentation@6-dev`. @stevepiercy
+- Fix broken links and redirects in documentation to be compatible with MyST. @stevepiercy
+- Update add-on internationalization. @ksuess
+- Add MyST and Sphinx basic configuration for rapid build and comparison against MkDocs builds. @stevepiercy
+- Fix many MyST and Sphinx warnings. @stevepiercy
+- Remove MkDocs configuration. See https://github.com/plone/volto/issues/3042 @stevepiercy
+- Add Plone docs to Intersphinx and fix broken link. @stevepiercy
+- Get version from `package.json` @sneridagh
+- Remove legacy folder in docs @sneridagh
+- Backport docs of RAZZLE_TESTING_ADDONS environment variables. See https://github.com/plone/volto/pull/3067/files#diff-00609ed769cd40cf3bc3d6fcc4431b714cb37c73cedaaea18fe9fc4c1c589597 @stevepiercy
+- Add missing developer-guidelines/typescript to toctree @stevepiercy
+- Add Netlify for preview of Sphinx builds for pull requests against `master` and `plone6-docs`. @stevepiercy
+- Clean up toctree errors by removing obsolete files, adding `:orphan:` field list, and reorganizing some files. @sneridagh and @stevepiercy
+- Switch to using netlify.toml to configure Netlify Python environment. @stevepiercy
+- Convert admonition syntax from Markdown to MyST. @sneridagh
+
 ## 15.0.0-alpha.5 (2022-02-16)
 
 ### Breaking

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -11,4 +11,3 @@ If a participant engages in harassing behavior, representatives of the community
 If you are being harassed, notice that someone else is being harassed, or have any other concerns, please act to intercede or ask for help from any member of the Plone Foundation, IRC chat admins, website admins, or organizers/representatives of any physical events put on under the auspices of the Plone Foundation.
 
 Source: https://plone.org/foundation/materials/foundation-resolutions/code-of-conduct (2019-09-29)
-
diff --git a/COMMITLINT.md b/COMMITLINT.md
@@ -4,75 +4,73 @@ Volto uses the (conventional commit specification)[https://www.conventionalcommi
 
 All commit messages should have the following form:
 
-````
+```
 <type>: <description>
-````
+```
 
 ## Fix
 
 A fix (PATCH in semantic versioning) looks like this:
 
-````
+```
 fix: correct minor typos in code
-````
+```
 
 ## Feature
 
 A new feature (MINOR in semantic versioning) looks like this:
 
-````
+```
 feat: add catalan language
-````
+```
 
 ## Breaking Change
 
 Breaking changes can be indicated by either appending a "!" to the type:
 
-````
+```
 refactor!: drop support for Node 6
-````
+```
 
 Or adding "BREAKING CHANGE" to the commit message body text:
 
-````
+```
 refactor!: drop support for Node 6
 
 BREAKING CHANGE: refactor to use JavaScript features not available in Node 6.
-````
+```
 
 ## Available Types
 
 In addition to "fix" and "feat" the following types are allowed:
 build:, chore:, ci:, docs:, style:, refactor:, perf:, test:
 
-
-
 Install commitlint:
 
-````
+```
 npm install --save-dev @commitlint/{config-conventional,cli}
-````
+```
 
 or via yarn:
 
-````
+```
 yarn add @commitlint/{config-conventional,cli}
-````
+```
 
 Create a commitlint.config.js file:
 
-````
+```
 echo "module.exports = {extends: ['@commitlint/config-conventional']}" > commitlint.config.js
-````
+```
 
 Add husky to package.json:
 
-````
+```
 {
   "husky": {
     "hooks": {
       "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
-    }  
+    }
   }
 }
-````
+```
diff --git a/Makefile b/Makefile
@@ -16,6 +16,16 @@ INSTANCE_PORT=8080
 DOCKER_IMAGE=plone/plone-backend:5.2.6
 KGS=plone.restapi==8.21.0 plone.volto==4.0.0a3 plone.rest==2.0.0a2 plone.app.iterate==4.0.2 plone.app.vocabularies==4.3.0
 
+# Sphinx variables
+# You can set these variables from the command line.
+SPHINXOPTS      ?=
+# Internal variables.
+SPHINXBUILD     = $(realpath bin/sphinx-build)
+SPHINXAUTOBUILD = $(realpath bin/sphinx-autobuild)
+DOCS_DIR        = ./docs/source/
+BUILDDIR        = ../_build/
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) .
+
 # Recipe snippets for reuse
 
 CHECKOUT_BASENAME=$(shell basename $(shell realpath ./))
@@ -92,19 +102,62 @@ test-clean:  ## Test in a separate, clean worktree to expose clean build issues
 # Leave the temporary worktree around for the developer to inspect.
 # Use the `$ make clean-tmp-worktrees` target to clean up all temporary worktrees
 
-.PHONY: docs-serve
-docs-serve:
-	(cd docs && ../bin/mkdocs serve)
-
-.PHONY: docs-build
-docs-build:
-# The build in netlify breaks because they have not installed ensurepip
-# So we should continue using virtualenv
-	virtualenv --python=python3 .
-	./bin/pip install -r requirements-docs.txt
-	(cd docs && ../bin/mkdocs build)
+.PHONY: storybook-build
+storybook-build:
 	yarn build-storybook -o docs/build/storybook
 
+bin/python:
+	python3 -m venv . || virtualenv --clear --python=python3 .
+	bin/python -m pip install --upgrade pip
+	bin/pip install -r requirements-docs.txt
+
+.PHONY: docs-clean
+docs-clean:  ## Clean current and legacy docs build directories, and Python virtual environment
+	cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/
+	rm -rf bin include lib
+	rm -rf docs/build
+
+.PHONY: docs-html
+docs-html: bin/python  ## Build html
+	cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: docs-livehtml
+docs-livehtml: bin/python  ## Rebuild Sphinx documentation on changes, with live-reload in the browser
+	cd "$(DOCS_DIR)" && ${SPHINXAUTOBUILD} \
+		--ignore "*.swp" \
+		-b html . "$(BUILDDIR)/html" $(SPHINXOPTS)
+
+.PHONY: docs-linkcheck
+docs-linkcheck: bin/python  ## Run linkcheck
+	cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+		"or in $(BUILDDIR)/linkcheck/ ."
+
+.PHONY: docs-linkcheckbroken
+docs-linkcheckbroken: bin/python  ## Run linkcheck and show only broken links
+	cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck | GREP_COLORS='0;31' egrep -wi broken --color=auto
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+		"or in $(BUILDDIR)/linkcheck/ ."
+
+.PHONY: docs-spellcheck
+docs-spellcheck: bin/python  ## Run spellcheck
+	cd $(DOCS_DIR) && LANGUAGE=$* $(SPHINXBUILD) -b spelling -j 4 $(ALLSPHINXOPTS) $(BUILDDIR)/spellcheck/$*
+	@echo
+	@echo "Spellcheck is finished; look for any errors in the above output " \
+		" or in $(BUILDDIR)/spellcheck/ ."
+
+.PHONY: netlify
+netlify:
+	pip install -r requirements-docs.txt
+	cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) ../$(BUILDDIR)/html
+
+.PHONY: docs-test
+docs-test: docs-clean docs-linkcheck docs-spellcheck  ## Clean docs build, then run linkcheck, spellcheck
+
 .PHONY: start
 # Run both the back-end and the front end
 start:

diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Volto
 
-<img align="right" width="300" alt="Volto png" src="./docs/logos/volto-colorful.png" />
+<img align="right" width="300" alt="Volto png" src="./logos/volto-colorful.png" />
 
 [![NPM](https://img.shields.io/npm/v/@plone/volto.svg)](https://www.npmjs.com/package/@plone/volto)
 [![Build Status Core](https://github.com/plone/volto/actions/workflows/core.yml/badge.svg)](https://github.com/plone/volto/actions)

diff --git a/SECURITY.md b/SECURITY.md
@@ -12,4 +12,3 @@ Volto is currently under very active development. Therefore we only support the
 ## Reporting a Vulnerability
 
 If you found a possible vulnerability please contact the Plone security team under [email protected].
-
Original file line number	Diff line number	Diff line change
Expand Up		@@ -11,4 +11,3 @@ If a participant engages in harassing behavior, representatives of the community
		If you are being harassed, notice that someone else is being harassed, or have any other concerns, please act to intercede or ask for help from any member of the Plone Foundation, IRC chat admins, website admins, or organizers/representatives of any physical events put on under the auspices of the Plone Foundation.

		Source: https://plone.org/foundation/materials/foundation-resolutions/code-of-conduct (2019-09-29)
Original file line number	Diff line number	Diff line change
Expand Up		@@ -12,4 +12,3 @@ Volto is currently under very active development. Therefore we only support the
		## Reporting a Vulnerability

		If you found a possible vulnerability please contact the Plone security team under [email protected].