DOCS add contributing guide and syntax summary

docs/contributing.md

@@ -0,0 +1,41 @@
+# 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/)
+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
+>> pre-commit install
+```
+
+Optionally you can run `black` and `flake8` separately:
+
+```shell
+>> black .
+>> flake8 .
+```
+
+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.

docs/index.md

@@ -34,6 +34,7 @@ maxdepth: 2
 caption: Contents
 ---
 syntax.md
+contributing.md
 ```
 
 ```{toctree}

docs/syntax.md

@@ -15,7 +15,45 @@ 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.
 
-Here are a few major extensions from the CommonMark flavor of markdown
+Below is a summary of the syntax 'tokens' parsed,
+and further details of a few major extensions from the CommonMark flavor of markdown
+
+## Parsed Token Classes
+
+Tokens are listed in their order of precedence.
+For more information, also see the [CommonMark Spec](https://spec.commonmark.org/0.28/), which the parser is tested against.
+
+### Block Tokens
+
+- **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**
 
 ## Directives - a block-level extension point
 

docs/wealth_dynamics_md.md

@@ -150,7 +150,12 @@ dynamics.
 
 The model we will study is
 
-$$w_{t+1} = (1 + r_{t+1}) s(w_t) + y_{t+1}$$
+```{math}
+---
+label: wealth_dynam_ah
+---
+w_{t+1} = (1 + r_{t+1}) s(w_t) + y_{t+1}
+```
 
 where
 
@@ -174,7 +179,15 @@ $$y_t = c_y \exp(z_t) + \exp(\mu_y + \sigma_y \zeta_t)$$
 Here $\{ (\epsilon_t, \xi_t, \zeta_t) \}$ is IID and standard normal in
 $\mathbb R^3$.
 
-$$s(w) = s_0 w \cdot \mathbb 1\{w \geq \hat w\}$$
+(sav_ah)=
+
+```{math}
+---
+label: sav_ah
+---
+s(w) = s_0 w \cdot \mathbb 1\{w \geq \hat w\}
+```
+
 
 where $s_0$ is a positive constant.
 

myst_parser/block_tokens.py

@@ -30,7 +30,6 @@
 
 # TODO add FieldList block token, see:
 # https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#field-lists
-# TODO target span (or role)
 
 
 class LineComment(block_token.BlockToken):