adding documentation (#13)

Author: choldgraf

.circleci/config.yml

@@ -0,0 +1,37 @@
+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 .[rtd]
+      - save_cache:
+          key: cache-pip
+          paths:
+            - ~/.cache/pip
+
+      # Build the docs
+      - run:
+          name: Build docs to store
+          command: |
+            sphinx-build -b html docs/ docs/_build/html
+
+      - store_artifacts:
+          path: docs/_build/html/
+          destination: html
+
+
+workflows:
+  version: 2
+  default:
+    jobs:
+      - build_docs

docs/Makefile

@@ -0,0 +1,20 @@
+# 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)

docs/README.md

@@ -0,0 +1,58 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "markdown-it-py"
+copyright = "2020, executable book project"
+author = "executable book project"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["myst_nb", "sphinx_copybutton"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_title = "markdown-it-py"
+html_theme = "sphinx_book_theme"
+html_theme_options = {
+    "use_edit_page_button": True,
+    "repository_url": "https://github.com/executablebooks/markdown-it-py",
+    "repository_branch": "master",
+    "path_to_docs": "docs",
+}
+
+# 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,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]

docs/conf.py

@@ -4,7 +4,7 @@ Before continuing, make sure you've read:
 
 1. [README](https://github.com/markdown-it/markdown-it#markdown-it)
 2. [API documentation](https://markdown-it.github.io/markdown-it/)
-3. [Architecture description](architecture.md)
+3. [Architecture description](architecture)
 
 
 ## General considerations for plugins.
@@ -34,7 +34,7 @@ Before continuing, make sure you've read:
 ## FAQ
 
 
-#### I need async rule, how to do it?
+### I need async rule, how to do it?
 
 Sorry. You can't do it directly. All complex parsers are sync by nature. But you
 can use workarounds:
@@ -48,7 +48,7 @@ Alternatively, you can render HTML, then parse it to DOM, or
 in a more convenient way.
 
 
-#### How to replace part of text token with link?
+### How to replace part of text token with link?
 
 The right sequence is to split text to several tokens and add link tokens in between.
 The result will be: `text` + `link_open` + `text` + `link_close` + `text`.
@@ -58,15 +58,15 @@ See implementations of [linkify](https://github.com/markdown-it/markdown-it/blob
 __Note.__ Don't try to replace text with HTML markup! That's not secure.
 
 
-#### Why my inline rule is not executed?
+### Why my inline rule is not executed?
 
 The inline parser skips pieces of texts to optimize speed. It stops only on [a small set of chars](https://github.com/markdown-it/markdown-it/blob/master/lib/rules_inline/text.js), which can be tokens. We did not made this list extensible for performance reasons too.
 
 If you are absolutely sure that something important is missing there - create a
 ticket and we will consider adding it as a new charcode.
 
 
-#### Why do you reject some useful things?
+### Why do you reject some useful things?
 
 We do a markdown parser. It should keep the "markdown spirit". Other things should
 be kept separate, in plugins, for example. We have no clear criteria, sorry.

docs/development.md

@@ -0,0 +1,9 @@
+```{include} ../README.md
+```
+
+```{toctree}
+using
+architecture
+development
+security
+```