consolidate contributing information. Fixes #305

Author: mr-c

CONTRIBUTING.md

@@ -43,7 +43,7 @@ and to meet some of our community members.
     you can submit a pull request (PR).
     Instructions for doing this are [included below][using-github].
 
-4. To build and run the user guide locally, see **Building** below  
+4. To build and run the user guide locally, see **Building** below
 
 **Note:** The published version of the user guide <https://www.commonwl.org/user_guide/> is built from the `release` branch.
 New changes are gathered on the default (`main`) branch which is built at <https://common-workflow-languageuser-guide.readthedocs.io/en/latest/>
@@ -125,6 +125,56 @@ source venv/bin/activate
 > correctly, but failure to deploy the production version after the pull request
 > gets merged.
 
+## Style Guide
+
+We must use the phrase "CWL standards" or "CWL open standards" when talking about CWL.
+We must use the word "specification" only when talking specifically about the CWL
+specification document.
+
+Whenever a page is updated we must verify that it does not break existing
+links, both internal and external. The `make html` command will fail if Sphinx detects broken links.
+It only works for links managed by Sphinx (i.e. table of contents links,
+or links to Markdown pages). For simple HTML links (e.g. `< href=>` or
+markdown external links) pull request reviewers must verify that links
+are still working after the change.
+
+Use “tool description” not “tool wrapper” for describing the first argument
+given to the `cwl-runner` or `cwltool` commands.
+
+### Code examples
+
+To include code into a Markdown file you have two options. For external files use
+the following command:
+
+````
+```{literalinclude} /_includes/cwl/hello_world.cwl
+:language: cwl
+```
+````
+
+For code examples in the same page, you can use fence blocks.
+
+````
+```bash
+echo "Hello world"
+```
+````
+
+If you would like to customize the syntax highlighting styles
+you will have to customize the Sphinx and Pygments settings.
+To preview Pygments output with different styles, use their
+[Pygments demo tool](https://pygments.org/demo/).
+
+### Creating Links
+
+Sphinx and the theme are configured to auto-generate anchor slug
+links for sections. So sections like ``## cwl standard`` are translated
+into an anchor link `#cwl-standard`.
+
+If you are having trouble with links to sections or code blocks, it might
+be due to duplicated sections, or to spaces or other characters. To
+preview the generated links, use the `myst-anchors` tool.
+
 ## Other Resources
 
 General discussion of [Common Workflow Language][cwl-site] project

README.md

@@ -1,9 +1,14 @@
-[![DOI](https://zenodo.org/badge/89621457.svg)](https://zenodo.org/badge/latestdoi/89621457)
+[![DOI for the latest version](https://zenodo.org/badge/89621457.svg)](https://zenodo.org/badge/latestdoi/89621457)
 
 [![Syntax Check](https://travis-ci.org/common-workflow-language/user_guide.svg?branch=main)](https://travis-ci.org/common-workflow-language/user_guide)
 
-[Released User guide for CWL v1.2.0](https://www.commonwl.org/user_guide/) : This is the released version which corresponds to the release branch.  
-[Read The Docs User guide for CWL v1.2.0](https://common-workflow-languageuser-guide.readthedocs.io/en/latest/) : This is the Read The Docs(RTD) version which corresponds to the main branch.
+
+This is the source of the official user guide for the Common Workflow Language standards.
+
+Releases are published at <https://www.commonwl.org/user_guide/> from the `release` branch.
+
+Preview of the next release is published at <https://common-workflow-languageuser-guide.readthedocs.io/en/latest/>
+based upon the default branch (`main`) using the Read The Docs (RTD) service.
 
 Original source:
 https://github.com/common-workflow-language/common-workflow-language/blob/a2a8a08b8c8d56f8f2ca6284ca4e9cbf23d19346/v1.0/UserGuide.yml
@@ -16,98 +21,6 @@ To edit the user guide:
 
 We'd like to ask you to familiarize yourself with our [Contribution Guide](CONTRIBUTING.md).
 
-## Style Guide
-
-We must use CWL standards or CWL open standards when talking about CWL.
-We must use specification only when talking specifically about the CWL
-specification document.
-
-Whenever a page is updated we must verify that it does not break existing
-links. The `make html` command will fail if Sphinx detects broken links.
-It only works for links managed by Sphinx (i.e. table of contents links,
-or links to Markdown pages). For simple HTML links (e.g. `< href=>` or
-markdown external links) pull request reviewers must verify that links
-are still working after the change.
-
-Use “tool description” not “tool wrapper” for describing the first argument
-given to the `cwl-runner` or `cwltool` commands.
-
-### Code examples
-
-To include code into a Markdown file you have two options. For external files use
-the following command:
-
-````
-```{literalinclude} /_includes/cwl/hello_world.cwl
-:language: cwl
-```
-````
-
-For code examples in the same page, you can use fence blocks.
-
-````
-```bash
-echo "Hello world"
-```
-````
-
-If you would like to customize the syntax highlighting styles
-you will have to customize the Sphinx and Pygments settings.
-To preview Pygments output with different styles, use their
-[Pygments demo tool](https://pygments.org/demo/).
-
-### Creating Links
-
-Sphinx and the theme are configured to auto-generate anchor slug
-links for sections. So sections like ``## cwl standard`` are translated
-into an anchor link `#cwl-standard`.
-
-If you are having trouble with links to sections or code blocks, it might
-be due to duplicated sections, or to spaces or other characters. To
-preview the generated links, use the `myst-anchors` tool.
-
-```bash
-$ (venv) myst-anchors basic-concepts.md
-<h1 id="basic-concepts"></h1>
-<h2 id="the-cwl-standard"></h2>
-<h2 id="implementations"></h2>
-<h2 id="cwl-objects-model"></h2>
-```
-
-You can also create reference anchor links anywhere on the page with
-``(test)=``, which can be used in the page as `#test` (these do not appear
-in the `myst-anchor` output).
-
-> Links to anchors in pages work only for Sphinx's autogenerated anchor links.
-> If you have an anchor for, for example, a code-block, that might cause the
-> build to fail: https://github.com/executablebooks/MyST-Parser/issues/564
-
-## Extensions
-
-We use MyST Parser with Sphinx. This gives us the best of both Sphinx and Markdown,
-while also supporting reStructuredText, Sphinx, and MyST extensions.
-
-### String Substitutions
-
-For convenience, we have the currently supported version of the specification as a
-constant in `conf.py`. We have it in two forms:
-
-- Markdown preformatted, i.e. \`v0.0\` which is formatted as `v0.0`
-- Plain text, i.e. v0.0
-
-Note that String Substitutions do not work with links. As workaround, you can use
-string formatting or replacements.
-
-```
-The CWL {{ cwl_version  }} Specification: {{ '<https://www.commonwl.org/{}/>'.format(cwl_version_text) }}
-```
-
-For more:
-
-- <https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2>
-- <https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-and-urls>
-- <https://github.com/executablebooks/MyST-Parser/issues/279>
-
 ## Authors
 
 A list of contributors to these materials can be found in [AUTHORS](AUTHORS.md)