Merge ExecutableBookProject/develop (#104)

.circleci/config.yml

@@ -0,0 +1,36 @@
+version: 2
+jobs:
+  build_docs:
+    docker:
+      - image: circleci/python:3.6-stretch
+    steps:
+      # Get our data and merge with upstream
+      - run: sudo apt-get update
+      - checkout
+
+      - restore_cache:
+          keys:
+            - cache-pip
+      - run: pip install --user -e .[sphinx,rtd]
+      - save_cache:
+          key: cache-pip
+          paths:
+            - ~/.cache/pip
+
+      # Build the docs
+      - run:
+          name: Build docs to store
+          command: |
+            cd docs
+            make html-strict
+
+      - store_artifacts:
+          path: docs/_build/html/
+          destination: html
+
+
+workflows:
+  version: 2
+  default:
+    jobs:
+      - build_docs

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: 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 '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Environment (please complete the following information):**
+ - Python Version [e.g. 3.7.1]
+ - Package Version [e.g. 0.1.0]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/documentation-improvements.md

@@ -0,0 +1,14 @@
+---
+name: Documentation Improvements
+about: Suggest improvements to the documentation
+title: ''
+labels: documentation
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. This section is unclear [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.pre-commit-config.yaml

@@ -4,7 +4,8 @@
 exclude: >
     (?x)^(
       \.vscode/settings\.json|
-      tests/commonmark/commonmark\.json
+      tests/test_commonmark/commonmark\.json|
+      .*\.xml
     )$
 
 repos:

.readthedocs.yml

@@ -0,0 +1,10 @@
+version: 2
+
+python:
+  version: 3
+  install:
+      - method: pip
+        path: .
+        extra_requirements:
+          - sphinx
+          - rtd

.travis.yml

@@ -12,17 +12,17 @@ matrix:
         env: TEST_TYPE="pre-commit"
 install:
   - pip install --upgrade pip wheel setuptools
-  - pip install git+https://github.com/ExecutableBookProject/mistletoe.git@myst
   - |
       if [[ "$TEST_TYPE" == "pre-commit" ]]; then
         pip install -e .[code_style]
       fi
   - |
       if [[ "$TEST_TYPE" == "pytest" ]]; then
-        pip install -e .[testing]
+        pip install -e .[testing,sphinx]
+        pip install coveralls
       fi
 before_script:
-    - (cd tests/commonmark && ./spec.sh)
+    - (cd tests/test_commonmark && ./spec.sh)
 script:
 - |
   if [[ "$TEST_TYPE" == "pytest" ]]; then

.vscode/settings.json

@@ -8,9 +8,12 @@
         "**/__pycache__": true,
         "**/.pytest_cache": true
     },
-    "editor.rulers": [88],
+    "editor.rulers": [
+        88
+    ],
     "python.formatting.provider": "black",
     "python.linting.pylintEnabled": false,
     "python.linting.flake8Enabled": true,
     "python.linting.enabled": true,
-}
+    "autoDocstring.customTemplatePath": "docstring.fmt.mustache"
+}

README.md

@@ -1,31 +1,83 @@
-# myst_parser
+# MyST-Parser
 
-[![Build Status](https://travis-ci.org/ExecutableBookProject/myst_parser.svg?branch=master)](https://travis-ci.org/ExecutableBookProject/myst_parser)
+[![Build Status](https://travis-ci.org/ExecutableBookProject/MyST-Parser.svg?branch=develop)](https://travis-ci.org/ExecutableBookProject/MyST-Parser)
+[![Coverage Status](https://coveralls.io/repos/github/ExecutableBookProject/MyST-Parser/badge.svg?branch=develop)](https://coveralls.io/github/ExecutableBookProject/MyST-Parser?branch=develop)
+[![Documentation Status](https://readthedocs.org/projects/myst-parser/badge/?version=latest)](https://myst-parser.readthedocs.io/en/latest/?badge=latest)
 
 An extended commonmark compliant parser, with bridges to docutils & sphinx.
 
-## Installing
+## Usage
 
-This parser currently requires the [ExecutableBookProject/mistletoe](https://github.com/ExecutableBookProject/mistletoe)
-fork of mistletoe (and the myst branch).
+```bash
+pip install -e "git+https://github.com/ExecutableBookProject/MyST-Parser.git#egg=myst-parser[sphinx]"
+```
+
+Or for package development:
 
-```console
-pip install git+https://github.com/ExecutableBookProject/mistletoe.git@myst
+```bash
+git clone https://github.com/ExecutableBookProject/MyST-Parser
+cd MyST-Parser
+git checkout develop
+pip install -e .[sphinx,code_style,testing,rtd]
 ```
 
+Note, this parser currently requires the [ExecutableBookProject/mistletoe](https://github.com/ExecutableBookProject/mistletoe)
+fork of mistletoe (included in the above installation).
+
+To use the MyST parser in Sphinx, simply add: `extensions = ["myst_parser"]` to your `conf.py`.
+
+## Parsed Token Classes
+
+For more information, also see the [CommonMark Spec](https://spec.commonmark.org/0.28/).
+
+### Block Tokens
+
+- **FrontMatter**: A YAML block at the start of the document enclosed by `---`
+- **HTMLBlock**: Any valid HTML (rendered in HTML output only)
+- **LineComment**: `% this is a comment`
+- **BlockCode**: indented text (4 spaces)
+- **Heading**: `# Heading` (levels 1-6)
+- **SetextHeading**: underlined header
+- **Quote**: `> this is a quote`
+- **CodeFence**: enclosed in 3 or more backticks.
+  If it starts with a `{name}`, then treated as directive.
+- **ThematicBreak**: `---`
+- **List**: bullet points or enumerated.
+- **Table**: Standard markdown table styles.
+- **Footnote**: A substitution for an inline link (e.g. `[key][name]`), which can have a reference target (no spaces), and an optional title (in `"`), e.g. `[key]: https://www.google.com "a title"`
+- **Paragraph**: General inline text
+
+### Span (Inline) Tokens
+
+- **Role**: `` `{name}`interpreted text` ``
+- **Math**: `$a=1$` or `$$a=1$$`
+- **HTMLSpan**: any valid HTML (rendered in HTML output only)
+- **EscapeSequence**: `\*`
+- **AutoLink**: `<http://www.google.com>`
+- **Target**: `(target)=` (precedes element to target, e.g. header)
+- **InlineCode**: `` `a=1` ``
+- **LineBreak**: Soft or hard (ends with spaces or `\`)
+- **Image**: `![alt](src "title")`
+- **Link**: `[text](target "title")` or `[text][key]` (key from `Footnote`)
+- **Strong**: `**strong**`
+- **Emphasis**: `*emphasis*`
+- **RawText**
+
 ## Contributing
 
+### Code Style
+
 Code style is tested using [flake8](http://flake8.pycqa.org),
 with the configuration set in `.flake8`,
 and code formatted with [black](https://github.com/ambv/black).
 
-Installing with `myst_parser[code_style]` makes the [pre-commit](https://pre-commit.com/)
+Installing with `myst-parser[code_style]` makes the [pre-commit](https://pre-commit.com/)
 package available, which will ensure this style is met before commits are submitted, by reformatting the code
 and testing for lint errors.
 It can be setup by:
 
 ```shell
->> cd myst_parser
+>> cd MyST-Parser
 >> pre-commit install
 ```
 
@@ -37,3 +89,18 @@ Optionally you can run `black` and `flake8` separately:
 ```
 
 Editors like VS Code also have automatic code reformat utilities, which can adhere to this standard.
+
+### Pull Requests
+
+To contribute, make Pull Requests to the `develop` branch (this is the default branch). A PR can consist of one or multiple commits. Before you open a PR, make sure to clean up your commit history and create the commits that you think best divide up the total work as outlined above (use `git rebase` and `git commit --amend`). Ensure all commit messages clearly summarise the changes in the header and the problem that this commit is solving in the body.
+
+Merging pull requests: There are three ways of 'merging' pull requests on GitHub:
+
+- Squash and merge: take all commits, squash them into a single one and put it on top of the base branch.
+    Choose this for pull requests that address a single issue and are well represented by a single commit.
+    Make sure to clean the commit message (title & body)
+- Rebase and merge: take all commits and 'recreate' them on top of the base branch. All commits will be recreated with new hashes.
+    Choose this for pull requests that require more than a single commit.
+    Examples: PRs that contain multiple commits with individually significant changes; PRs that have commits from different authors (squashing commits would remove attribution)
+- 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.

conftest.py

@@ -0,0 +1 @@
+pytest_plugins = "sphinx.testing.fixtures"

docs/.gitignore

@@ -0,0 +1 @@
+api/

docs/Makefile

@@ -0,0 +1,27 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# raise warnings to errors
+html-strict:
+	@$(SPHINXBUILD) -b html -nW --keep-going "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
+clean:
+	rm -r $(BUILDDIR)