📚 DOCS: Update and improve

Author: chrisjsewell

.gitignore

@@ -137,6 +137,6 @@ apidoc/
 __pycache__/
 .ropeproject/
 *.egg-info/
-vscode/
+.vscode/
 
 docs/api/

.readthedocs.yml

@@ -7,3 +7,7 @@ python:
         path: .
         extra_requirements:
           - rtd
+
+sphinx:
+  builder: html
+  fail_on_warning: true

.vscode/settings.json

@@ -1,53 +1,28 @@
 # markdown-it-py
 
-[![Github-DI][github-ci]][github-link]
+[![Github-CI][github-ci]][github-link]
 [![Coverage Status][codecov-badge]][codecov-link]
 [![PyPI][pypi-badge]][pypi-link]
 [![Conda][conda-badge]][conda-link]
 [![Code style: black][black-badge]][black-link]
 
-> Markdown parser done right. Fast and easy to extend.
+> Markdown parser done right.
 
-- Follows the __[CommonMark spec]__ + adds syntax extensions & sugar (URL autolinking, typographer).
-- Configurable syntax! You can add new rules and even replace existing ones.
-- High speed.
-- [Safe][security-doc] by default.
-- Pluginable
+- Follows the __[CommonMark spec](http://spec.commonmark.org/)__ for baseline parsing
+- Configurable syntax: you can add new rules and even replace existing ones.
+- Pluggable: Adds syntax extensions to extend the parser (see the [plugin list][md-plugins]).
+- High speed (see our [benchmarking tests][md-performance])
+- [Safe by default][md-security]
 
-
-This is a Python port of [markdown-it],
-and some of its associated plugins.
-It is still under development, so for now should be used with caution.
+This is a Python port of [markdown-it], and some of its associated plugins.
+For more details see: <https://markdown-it-py.readthedocs.io>.
 
 For details on [markdown-it] itself, see:
 
 - The __[Live demo](https://markdown-it.github.io)__
 - [The markdown-it README][markdown-it-readme]
 
-
-__Table of content__
-
-- [markdown-it-py](#markdown-it-py)
-  - [The Port](#the-port)
-  - [Install](#install)
-  - [Basic usage](#basic-usage)
-  - [Benchmarking](#benchmarking)
-  - [Syntax extensions](#syntax-extensions)
-  - [Authors](#authors)
-  - [References / Thanks](#references--thanks)
-    - [Related Links](#related-links)
-    - [Other Ports](#other-ports)
-
-
-## The Port
-
-Details of the port can be found in `markdown_it/port.yaml` and in `port.yaml`
-within the extension folders. But the driving design philosophy has been to change as little of the
-fundamental code structure (file names, function name, etc) as possible, just sprinkling in a little Python syntactic sugar.
-It is very simple to write complimentary extensions for both language implementations!
-
-
-## Install
+## Installation
 
 ```bash
 conda install -c conda-forge markdown-it-py
@@ -59,14 +34,8 @@ or
 pip install markdown-it-py
 ```
 
-
 ## Basic usage
 
-See also:
-
-- [Using `markdown_it`][using-the-api] - for an executable notebook guide to the API
-- [Development info] - for plugins writers.
-
 ```python
 from markdown_it import MarkdownIt
 from markdown_it.extensions.front_matter import front_matter_plugin
@@ -109,81 +78,14 @@ Type Ctrl-D to complete input, or Ctrl-C to exit.
 </blockquote>
 ```
 
-## Benchmarking
-
-markdown-it-py is the fastest _**CommonMark compliant**_ parser written in python!
-
-```console
-$ markdown-it-bench -n 30
-Test document: spec.md
-Test iterations: 30
-Running 7 test(s) ...
-=====================
-[mistune         (0.8.4): 3.62 s]*
-markdown-it-py   (0.1.0): 9.03 s
-mistletoe        (0.10.0): 9.89 s
-commonmark-py    (0.9.1): 20.82 s
-pymarkdown       (3.2.1): 34.50 s
-pymarkdown:extra (3.2.1): 41.86 s
-panflute         (1.12.5): 35.02 s
-```
-
-As you can see, `markdown-it-py` doesn't pay with speed for it's flexibility.
-
-\*Note `mistune` is not CommonMark compliant, which is what allows for its
-faster parsing, at the expense of issues, for example, with nested inline parsing.
-See [mistletoes's explanation](https://github.com/miyuchina/mistletoe#performance)
-for further details.
-
-
-## Syntax extensions
-
-Embedded (enabled when using the `"default"` preset configuration):
-
-- [Tables](https://help.github.com/articles/organizing-information-with-tables/) (GFM)
-- [Strikethrough](https://help.github.com/articles/basic-writing-and-formatting-syntax/#styling-text) (GFM)
-
-*Via* plugins:
-
-A list of plugins that have/can be ported:
-
-- [subscript](https://github.com/markdown-it/markdown-it-sub)
-- [superscript](https://github.com/markdown-it/markdown-it-sup)
-- [footnote](https://github.com/markdown-it/markdown-it-footnote)
-- [definition list](https://github.com/markdown-it/markdown-it-deflist)
-- [abbreviation](https://github.com/markdown-it/markdown-it-abbr)
-- [emoji](https://github.com/markdown-it/markdown-it-emoji)
-- [custom container](https://github.com/markdown-it/markdown-it-container)
-- [insert](https://github.com/markdown-it/markdown-it-ins)
-- [mark](https://github.com/markdown-it/markdown-it-mark)
-- ... and [others](https://www.npmjs.org/browse/keyword/markdown-it-plugin)
-
-
-## Authors
-
-- Chris Sewell [github/chrisjsewell](https://github.com/chrisjsewell)
-
 ## References / Thanks
 
-Big thanks to the authors of [markdown-it]
+Big thanks to the authors of [markdown-it]:
 
 - Alex Kocharin [github/rlidwka](https://github.com/rlidwka)
 - Vitaly Puzrin [github/puzrin](https://github.com/puzrin)
 
-Also [John MacFarlane](https://github.com/jgm) for his work on the
-CommonMark spec and reference implementations.
-
-### Related Links
-
-- https://github.com/jgm/CommonMark - reference CommonMark implementations in C & JS,
-  also contains latest spec & online demo.
-- http://talk.commonmark.org - CommonMark forum, good place to collaborate
-  developers' efforts.
-
-### Other Ports
-
-- [motion-markdown-it](https://github.com/digitalmoksha/motion-markdown-it) - Ruby/RubyMotion
-
+Also [John MacFarlane](https://github.com/jgm) for his work on the CommonMark spec and reference implementations.
 
 [github-ci]: https://github.com/ExecutableBookProject/markdown-it-py/workflows/Python%20package/badge.svg?branch=master
 [github-link]: https://github.com/ExecutableBookProject/markdown-it-py
@@ -199,6 +101,6 @@ CommonMark spec and reference implementations.
 [CommonMark spec]: http://spec.commonmark.org/
 [markdown-it]: https://github.com/markdown-it/markdown-it
 [markdown-it-readme]: https://github.com/markdown-it/markdown-it/blob/master/README.md
-[security-doc]: https://github.com/ExecutableBookProject/markdown-it-py/tree/master/docs/security.md
-[using-the-api]: https://github.com/ExecutableBookProject/markdown-it-py/tree/master/docs/using.md
-[Development info]: https://github.com/ExecutableBookProject/markdown-it-py/tree/master/docs/development.md
+[md-security]: https://github.com/ExecutableBookProject/markdown-it-py/tree/master/docs/security.md
+[md-performance]: https://markdown-it-py.readthedocs.io/en/latest/security.html
+[md-plugins]: https://markdown-it-py.readthedocs.io/en/latest/plugins.html

CONTRIBUTING.md

@@ -18,3 +18,11 @@ help:
 # "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)
+
+# increase logging level to verbose
+html-verbose:
+	@$(SPHINXBUILD) -b html -v "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)

README.md

@@ -1,5 +1,6 @@
-# markdown-it design principles
+(md/architecture)=
 
+# markdown-it design principles
 
 ## Data flow
 

docs/Makefile

@@ -33,6 +33,7 @@
     "sphinx.ext.intersphinx",
     "myst_nb",
     "sphinx_copybutton",
+    "sphinx_panels",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -57,6 +58,7 @@
     "repository_branch": "master",
     "path_to_docs": "docs",
 }
+panels_add_boostrap_css = False
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,