updating documentation (#131)

Author: choldgraf

.github/workflows/tests.yml

@@ -45,7 +45,7 @@ jobs:
         pytest --cov=myst_parser --cov-report=xml --cov-report=term-missing
         coverage xml
     - name: Upload to Codecov
-      if: matrix.python-version == 3.7 && github.repository == 'ExecutableBookProject/MyST-Parser'
+      if: matrix.python-version == 3.7 && github.repository == 'executablebooks/MyST-Parser'
       uses: codecov/codecov-action@v1
       with:
         name: myst-nb-pytests-py3.7

README.md

@@ -27,18 +27,18 @@ pip install myst-parser[sphinx]
 Or for package development:
 
 ```bash
-git clone https://github.com/ExecutableBookProject/MyST-Parser
+git clone https://github.com/executablebooks/MyST-Parser
 cd MyST-Parser
 git checkout master
 pip install -e .[sphinx,code_style,testing,rtd]
 ```
 
 To use the MyST parser in Sphinx, simply add: `extensions = ["myst_parser"]` to your `conf.py`.
 
-[github-ci]: https://github.com/ExecutableBookProject/MyST-Parser/workflows/continuous-integration/badge.svg?branch=master
-[github-link]: https://github.com/ExecutableBookProject/MyST-Parser
-[codecov-badge]: https://codecov.io/gh/ExecutableBookProject/MyST-Parser/branch/master/graph/badge.svg
-[codecov-link]: https://codecov.io/gh/ExecutableBookProject/MyST-Parser
+[github-ci]: https://github.com/executablebooks/MyST-Parser/workflows/continuous-integration/badge.svg?branch=master
+[github-link]: https://github.com/executablebooks/MyST-Parser
+[codecov-badge]: https://codecov.io/gh/executablebooks/MyST-Parser/branch/master/graph/badge.svg
+[codecov-link]: https://codecov.io/gh/executablebooks/MyST-Parser
 [rtd-badge]: https://readthedocs.org/projects/myst-parser/badge/?version=latest
 [rtd-link]: https://myst-parser.readthedocs.io/en/latest/?badge=latest
 [black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg

docs/conf.py

@@ -53,9 +53,9 @@
 html_theme = "sphinx_book_theme"
 html_logo = "_static/logo.png"
 html_theme_options = {
-    "github_url": "https://github.com/ExecutableBookProject/MyST-Parser",
-    "repository_url": "https://github.com/ExecutableBookProject/MyST-Parser",
-    "expand_sections": ["using/index"],
+    "github_url": "https://github.com/executablebooks/MyST-Parser",
+    "repository_url": "https://github.com/executablebooks/MyST-Parser",
+    "expand_sections": ["examples/index"],
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,

docs/develop/contributing.md

@@ -70,12 +70,12 @@ Merging pull requests: There are three ways of 'merging' pull requests on GitHub
 - Merge with merge commit: put all commits as they are on the base branch, with a merge commit on top
     Choose for collaborative PRs with many commits. Here, the merge commit provides actual benefits.
 
-[github-ci]: https://github.com/ExecutableBookProject/MyST-Parser/workflows/continuous-integration/badge.svg?branch=master
-[github-link]: https://github.com/ExecutableBookProject/MyST-Parser
-[codecov-badge]: https://codecov.io/gh/ExecutableBookProject/MyST-Parser/branch/master/graph/badge.svg
-[codecov-link]: https://codecov.io/gh/ExecutableBookProject/MyST-Parser
-[circleci-badge]: https://circleci.com/gh/ExecutableBookProject/MyST-Parser.svg?style=shield
-[circleci-link]: https://circleci.com/gh/ExecutableBookProject/MyST-Parser
+[github-ci]: https://github.com/executablebooks/MyST-Parser/workflows/continuous-integration/badge.svg?branch=master
+[github-link]: https://github.com/executablebooks/MyST-Parser
+[codecov-badge]: https://codecov.io/gh/executablebooks/MyST-Parser/branch/master/graph/badge.svg
+[codecov-link]: https://codecov.io/gh/executablebooks/MyST-Parser
+[circleci-badge]: https://circleci.com/gh/executablebooks/MyST-Parser.svg?style=shield
+[circleci-link]: https://circleci.com/gh/executablebooks/MyST-Parser
 [rtd-badge]: https://readthedocs.org/projects/myst-parser/badge/?version=latest
 [rtd-link]: https://myst-parser.readthedocs.io/en/latest/?badge=latest
 [black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg

docs/index.md

@@ -1,27 +1,61 @@
 MyST - Markedly Structured Text
 ===============================
 
-MyST is a markdown flavor that implements the best parts of reStructuredText.
-It provides a way to call Sphinx directives and roles from within Markdown.
-It is a *slight* extension of CommonMark markdown.
-
-This project provides a parser for this flavor of markdown, as well as a bridge between
-MyST syntax and {doc}`Sphinx <sphinx:intro>`. This allows for native markdown support for roles and
-directives.
-
-```{warning}
-The MyST parser is in an alpha stage, and may have breaking changes to its implementation
-and to the syntax that it supports. Use at your own risk. If you find any issues,
-please report them
-[in the MyST issues](https://github.com/ExecutableBookProject/meta/issues/24)
+**A fully-functional markdown flavor and parser for Sphinx.**
+
+MyST allows you to write Sphinx documentation entirely in markdown.
+It is an attempt to have the best of both worlds: the flexibility
+and extensibility of Sphinx with the simplicity and readability of Markdown.
+
+MyST has the following main features:
+
+* **[A markdown parser for Sphinx](parse-with-sphinx)**. You can write your entire
+  {doc}`Sphinx documentation <sphinx:intro>` in markdown.
+* **[Call Sphinx directives and roles from within Markdown](syntax/directives)**,
+  allowing you to extend your document via Sphinx extensions.
+* **[Extended Markdown syntax for useful rST features](extended-block-tokens)**, such
+  as line commenting and footnotes.
+* **[A Sphinx-independent parser of MyST markdown](using/use_api)** that can be extended
+  to add new functionality and outputs for MyST.
+* **[A superset of CommonMark markdown][commonmark]**. Any CommonMark markdown
+  (such as Jupyter Notebook markdown) is natively supported by the MyST parser.
+
+See {doc}`using/intro` to get started.
+
+```{note}
+The MyST parser is in a beta stage, and may change rapidly in its implementation
+and machinery. Use at your own risk. If you find any issues, please report them
+[in the MyST issues](https://github.com/executablebooks/meta/issues/24)
 ```
 
 ```{tip}
 Check out the [MyST-Markdown VS Code extension](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight),
 for MyST extended syntax highlighting.
 ```
 
-## Why a new flavor of markdown?
+## Site contents
+
+```{toctree}
+---
+maxdepth: 2
+caption: Using MyST Markdown
+---
+using/intro.md
+using/syntax.md
+using/use_api.md
+```
+
+```{toctree}
+---
+maxdepth: 2
+caption: Reference and contributing
+---
+examples/index.md
+develop/index.md
+api/index.md
+```
+
+## Why MyST markdown?
 
 While markdown is ubiquitous, it is not powerful enough for writing modern,
 fully-featured documentation. Some flavors of markdown support features needed for this,
@@ -34,7 +68,7 @@ particular, Sphinx defines two extension points that are extremely useful:
 
 **This project is an attempt at combining the simplicity and readability of Markdown
 with the power and flexibility of reStructuredText and the Sphinx platform.** It
-starts with the CommonMark markdown specification, and selectively adds a few extra
+starts with the [CommonMark markdown specification][commonmark], and selectively adds a few extra
 syntax pieces to utilize the most powerful parts of reStructuredText.
 
 ```{note}
@@ -50,15 +84,9 @@ decides on an "official" extension syntax, we will likely utilize this syntax fo
 MyST.
 ```
 
-Here are the site contents:
+## Acknowledgements
 
-```{toctree}
----
-maxdepth: 2
-caption: Contents
----
-using/index.md
-examples/index.md
-develop/index.md
-api/index.md
-```
+The MyST markdown language and MyST parser are both supported by the open community,
+[The Executable Book Project](https://executablebooks.org).
+
+[commonmark]: https://commonmark.org/

docs/using/index.md

@@ -26,7 +26,7 @@ pip install myst-parser[sphinx]
 Or for package development:
 
 ```bash
-git clone https://github.com/ExecutableBookProject/MyST-Parser
+git clone https://github.com/executablebooks/MyST-Parser
 cd MyST-Parser
 git checkout master
 pip install -e .[sphinx,code_style,testing,rtd]
@@ -37,6 +37,7 @@ pip install -e .[sphinx,code_style,testing,rtd]
 [conda-badge]: https://anaconda.org/conda-forge/myst-parser/badges/version.svg
 [conda-link]: https://anaconda.org/conda-forge/myst-parser
 
+(parse-with-sphinx)=
 ## Parsing MyST with Sphinx
 
 Sphinx is a documentation generator for building a website or book from multiple source documents and assets. To get started with Sphinx, see their [Quickstart Guide](https://www.sphinx-doc.org/en/master/usage/quickstart.html).
@@ -62,7 +63,7 @@ myst_config = {"disable_syntax": ["emphasis"], "math_delimiters": "brackets"}
 ```{seealso}
 The {py:class}`~myst_parser.sphinx_parser.MystParser` class API
 and
-[markdown-it-py](https://github.com/ExecutableBookProject/markdown-it-py)
+[markdown-it-py](https://github.com/executablebooks/markdown-it-py)
 for the list of syntax elements (known as rules) that you can disable.
 ```
 

docs/using/intro.md

@@ -3,17 +3,13 @@
 # The MyST Syntax Guide
 
 As a base, MyST adheres to the [CommonMark specification](https://spec.commonmark.org/).
-For this, it uses the [markdown-it-py](https://github.com/ExecutableBookProject/markdown-it-py) parser,
+For this, it uses the [markdown-it-py](https://github.com/executablebooks/markdown-it-py) parser,
 which is a well-structured markdown parser for Python that is CommonMark-compliant
 and also extensible.
 
-MyST adds several new syntax options that extend its functionality to be used
+MyST adds several new syntax options to CommonMark in order to be used
 with Sphinx, the documentation generation engine used extensively in the Python
-ecosystem. Sphinx uses reStructuredText by default, which is both more
-powerful than Markdown, and also (arguably) more complex to use.
-
-This project is an attempt to have the best of both worlds: the flexibility
-and extensibility of Sphinx with the simplicity and readability of Markdown.
+ecosystem.
 
 Below is a summary of the syntax 'tokens' parsed,
 and further details of a few major extensions from the CommonMark flavor of markdown.
@@ -22,16 +18,20 @@ and further details of a few major extensions from the CommonMark flavor of mark
 % {ref}`MyST Extended AST Tokens API <api/tokens>`
 % ```
 
-## Parsed Token
-
 MyST builds on the tokens defined by markdown-it, to extend the syntax
 described in the [CommonMark Spec](https://spec.commonmark.org/0.29/), which the parser is tested against.
 
 % TODO link to markdown-it documentation
 
-### Block Tokens
+## Block Tokens
+
+Block tokens span multiple lines of content. They are broken down into two sections:
 
-#### Extended block tokens
+* {ref}`extended-block-tokens` contains *extra* tokens that are not in CommonMark.
+* {ref}`commonmark-block-tokens` contains CommonMark tokens that also work, for reference.
+
+(extended-block-tokens)=
+### Extended block tokens
 
 `````{list-table}
 :header-rows: 1
@@ -89,7 +89,8 @@ described in the [CommonMark Spec](https://spec.commonmark.org/0.29/), which the
     ```
 `````
 
-#### CommonMark tokens
+(commonmark-block-tokens)=
+### CommonMark tokens
 
 `````{list-table}
 :header-rows: 1
@@ -156,9 +157,16 @@ described in the [CommonMark Spec](https://spec.commonmark.org/0.29/), which the
 
 `````
 
-### Span (Inline) Tokens
+## Span (Inline) Tokens
+
+Span (or inline) tokens are defined on a single line of content. They are broken down into two
+sections below:
+
+* {ref}`extended-span-tokens` contains *extra* tokens that are not in CommonMark.
+* {ref}`commonmark-span-tokens` contains CommonMark tokens that also work, for reference.
 
-#### Extended inline tokens
+(extended-span-tokens)=
+### Extended inline tokens
 
 `````{list-table}
 :header-rows: 1
@@ -191,7 +199,8 @@ described in the [CommonMark Spec](https://spec.commonmark.org/0.29/), which the
     ```
 `````
 
-#### CommonMark inline tokens
+(commonmark-span-tokens)=
+### CommonMark inline tokens
 
 `````{list-table}
 :header-rows: 1

docs/using/syntax.md

@@ -3,7 +3,7 @@
 MyST-Parser may be used as an API *via* the `myst_parser` package.
 
 ```{seealso}
-- The [markdown-it-py](https://github.com/ExecutableBookProject/markdown-it-py) package
+- The [markdown-it-py](https://github.com/executablebooks/markdown-it-py) package
 - {ref}`The MyST-Parser API <api/main>`
 ```
 

docs/using/use_api.md

@@ -11,7 +11,7 @@
     ),
     long_description=open("README.md").read(),
     long_description_content_type="text/markdown",
-    url="https://github.com/ExecutableBookProject/MyST-Parser",
+    url="https://github.com/executablebooks/MyST-Parser",
     project_urls={"Documentation": "https://myst-parser.readthedocs.io"},
     author="Chris Sewell",
     author_email="[email protected]",