Improve documentation

Add more hyperlinks and move badges to development section

docs/index.md

@@ -2,18 +2,9 @@
 
 # mistletoe-ebp
 
-[![CI Status][travis-badge]][travis-link]
-[![Coverage][coveralls-badge]][coveralls-link]
-[![Code style: black][black-badge]][black-link]
-[![PyPI][pypi-badge]][pypi-link]
-[![Conda][conda-badge]][conda-link]
-
 mistletoe is a Markdown parser in pure Python,
 designed to be fast, spec-compliant and fully customizable.
 
-This is a version of [mistletoe] maintained by the [Excutable Book Project (EBP)][ebp-link]. It tracks the `myst` branch of [ExecutableBookProject/mistletoe](https://github.com/ExecutableBookProject/mistletoe)
-which eventually, it is hoped, will be merged into mistletoe itself.
-
 Apart from being the fastest
 CommonMark-compliant Markdown parser implementation in pure Python,
 mistletoe also supports easy definitions of custom tokens.
@@ -23,15 +14,23 @@ without touching any of the core components.
 
 Remember to spell mistletoe in lowercase!
 
+```{note}
+This is a version of [mistletoe] maintained by the [Excutable Book Project (EBP)][ebp-link].
+It tracks the `myst` branch of [ExecutableBookProject/mistletoe](https://github.com/ExecutableBookProject/mistletoe)
+which eventually, it is hoped, will be merged into mistletoe itself.
+
+[ebp-link]: https://github.com/ExecutableBookProject
+[mistletoe]: https://github.com/miyuchina/mistletoe
+```
+
 ## Features
 
 * **Fast**:
   mistletoe is the fastest implementation of CommonMark in Python,
   that is, 2 to 3 times as fast as [Commonmark-py][commonmark-py],
   and still roughly 30% faster than [Python-Markdown][python-markdown].
   Running with PyPy yields comparable performance with [mistune][mistune].
-
-  See the [performance](#performance) section for details.
+  See the {ref}`Performance section<intro/performance>` for details.
 
 * **Spec-compliant**:
   CommonMark is [a useful, high-quality project][oilshell].
@@ -43,9 +42,14 @@ Remember to spell mistletoe in lowercase!
   Strikethrough and tables are supported natively,
   and custom block-level and span-level tokens can easily be added.
   Writing a new renderer for mistletoe is a relatively
-  trivial task.
+  trivial task. See the {ref}`Developer section <develop/intro>` for details.
 
-  You can even write [a Lisp][scheme] in it.
+* **LSP compliant**:
+  `mistletoe-ebp` aims to make it easy to use in implementations of the
+  [Language Server Protocol][lsp], the requirements being that;
+  (a) it is thread-safe for asynchronous parsing, and
+  (b) the line and character ranges of the source text are recorded
+  for each element in the syntax tree.
 
 Some alternative output formats:
 
@@ -79,18 +83,6 @@ using/contributing.md
 api/index.rst
 ```
 
-[ebp-link]: https://github.com/ExecutableBookProject
-[travis-badge]: https://travis-ci.org/ExecutableBookProject/mistletoe-ebp.svg?branch=master
-[travis-link]: https://travis-ci.org/ExecutableBookProject/mistletoe-ebp
-[coveralls-badge]: https://coveralls.io/repos/github/ExecutableBookProject/mistletoe-ebp/badge.svg?branch=master
-[coveralls-link]: https://coveralls.io/github/ExecutableBookProject/mistletoe-ebp?branch=master
-[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
-[pypi-badge]: https://img.shields.io/pypi/v/mistletoe-ebp.svg
-[pypi-link]: https://pypi.org/project/mistletoe-ebp
-[conda-badge]: https://anaconda.org/conda-forge/mistletoe-ebp/badges/version.svg
-[conda-link]: https://anaconda.org/conda-forge/mistletoe-ebp
-[black-link]: https://github.com/ambv/black
-[mistletoe]: https://github.com/miyuchina/mistletoe
 [mistune]: https://github.com/lepture/mistune
 [python-markdown]: https://github.com/waylan/Python-Markdown
 [python-markdown2]: https://github.com/trentm/python-markdown2
@@ -102,3 +94,4 @@ api/index.rst
 [example-392]: https://spec.commonmark.org/0.28/#example-392
 [icon]: https://www.freepik.com
 [cc-by]: https://creativecommons.org/licenses/by/3.0/us/
+[lsp]: https://microsoft.github.io/language-server-protocol/

docs/using/contributing.md

@@ -1,3 +1,5 @@
+(contribute)=
+
 # Contributing
 
 ## Code Style

docs/using/develop.md

@@ -2,6 +2,12 @@
 
 ## Developer's Guide
 
+[![CI Status][travis-badge]][travis-link]
+[![Coverage][coveralls-badge]][coveralls-link]
+[![Code style: black][black-badge]][black-link]
+[![PyPI][pypi-badge]][pypi-link]
+[![Conda][conda-badge]][conda-link]
+
 To understand the core tokens that mistletoe parses, take a look at:
 
 - {ref}`tokens/base`
@@ -186,3 +192,15 @@ with open('foo.md', 'r') as fin:
     with GithubWikiRenderer() as renderer:
         rendered = renderer.render(Document.read(fin))
 ```
+
+
+[travis-badge]: https://travis-ci.org/ExecutableBookProject/mistletoe-ebp.svg?branch=master
+[travis-link]: https://travis-ci.org/ExecutableBookProject/mistletoe-ebp
+[coveralls-badge]: https://coveralls.io/repos/github/ExecutableBookProject/mistletoe-ebp/badge.svg?branch=master
+[coveralls-link]: https://coveralls.io/github/ExecutableBookProject/mistletoe-ebp?branch=master
+[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
+[pypi-badge]: https://img.shields.io/pypi/v/mistletoe-ebp.svg
+[pypi-link]: https://pypi.org/project/mistletoe-ebp
+[conda-badge]: https://anaconda.org/conda-forge/mistletoe-ebp/badges/version.svg
+[conda-link]: https://anaconda.org/conda-forge/mistletoe-ebp
+[black-link]: https://github.com/ambv/black

docs/using/intro.md

@@ -1,4 +1,4 @@
-# Using mistletoe
+# Getting Started
 
 (intro/install)=
 
@@ -17,15 +17,17 @@ or *via* pip:
 pip install mistletoe-ebp
 ```
 
-Alternatively, clone the repo:
+Alternatively, for code development, clone the repo:
 
 ```sh
 git clone https://github.com/ExecutableBookProject/mistletoe-ebp.git
 cd mistletoe-ebp
 pip install -e .[testing,code_style]
 ```
 
-<!-- See the [contributing][contributing] doc for how to contribute to mistletoe. -->
+```{seealso}
+The {ref}`Contributing section <contribute>` to contribute to mistletoe's development!
+```
 
 (intro/usage)=
 
@@ -158,20 +160,21 @@ Running 7 test(s) ...
 markdown        (3.2.1): 31.13 s
 markdown:extra  (3.2.1): 42.45 s
 mistune         (0.8.4): 11.49 s
-commonmark      (x.x.x): 47.94 s
+commonmark      (0.9.1): 47.94 s
 mistletoe       (0.9.4): 35.58 s
 mistletoe:extra (0.9.4): 40.37 s
 panflute        (1.12.5): 168.06 s
 ```
 
 notes:
 
-- `markdown` without `extra` does not parse fenced code blocks or tables
-- `mistletoe` is CommonMark compliant and `mistletoe:extra`
+- `markdown` without `extra` does not parse some CommonMark syntax,
+  like fenced code blocks (see [Python-Markdown Extra](https://python-markdown.github.io/extensions/extra/))
+- `mistletoe` uses only CommonMark compliant tokens, whereas `mistletoe:extra`
   includes {ref}`tokens/extension`.
-- `panflute` calls pandoc *via* a subprocess
+- `panflute` calls [pandoc](https://pandoc.org/) *via* a subprocess
 
-We notice that Mistune is the fastest Markdown parser,
+We notice that [Mistune][mistune] is the fastest Markdown parser,
 and by a good margin, which demands some explanation.
 mistletoe's biggest performance penalty
 comes from stringently following the CommonMark spec,
@@ -194,7 +197,7 @@ The natural interpretation is:
 <p><em><strong>foo</strong> bar</em></p>
 ```
 
-... and it is indeed the output of Python-Markdown, Commonmark-py and mistletoe.
+... and it is indeed the output of [Python-Markdown], [Commonmark-py] and mistletoe.
 Mistune (version 0.8.3) greedily parses the first two asterisks
 in the first delimiter run as a strong-emphasis opener,
 the second delimiter run as its closer,
@@ -235,17 +238,18 @@ It is nevertheless *highly likely* that,
 when Mistune implements all the necessary context checks,
 it will suffer from the same performance penalties.
 
-Contextual analysis is why Python-Markdown is slow, and why CommonMark-py is slower.
+Contextual analysis is why [Python-Markdown] is slow,
+and why [CommonMark-py] is slower.
 The lack thereof is the reason mistune enjoys stellar performance
 among similar parser implementations,
 as well as the limitations that come with these performance benefits.
 
 If you want an implementation that focuses on raw speed,
 mistune remains a solid choice.
 If you need a spec-compliant and readily extensible implementation, however,
-mistletoe is still marginally faster than Python-Markdown,
+mistletoe is still marginally faster than [Python-Markdown],
 while supporting more functionality (lists in block quotes, for example),
-and significantly faster than CommonMark-py.
+and significantly faster than [CommonMark-py].
 
 One last note: another bottleneck of mistletoe compared to mistune
 is the function overhead. Because, unlike mistune, mistletoe chooses to split
@@ -264,10 +268,10 @@ mistletoe: 15.088351159000013
 ```
 
 [conda-env]: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-with-commands
-[mistune]: https://github.com/lepture/mistune
-[python-markdown]: https://github.com/waylan/Python-Markdown
+[mistune]: https://mistune.readthedocs.io
+[Python-Markdown]: https://Python-Markdown.github.io
 [python-markdown2]: https://github.com/trentm/python-markdown2
-[commonmark-py]: https://github.com/rtfd/CommonMark-py
+[CommonMark-py]: https://commonmarkpy.readthedocs.io
 [oilshell]: https://www.oilshell.org/blog/2018/02/14.html
 [commonmark]: https://spec.commonmark.org/
 [contrib]: https://github.com/ExecutableBookProject/mistletoe-ebp/tree/master/contrib