From ce750519a3e5727b7b9192f9f23f4f9b2b540fcd Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Fri, 9 Aug 2019 11:16:58 -0700 Subject: [PATCH 1/3] Setup release 0.6.0 --- CHANGELOG.md | 31 +++++++++++++++++++++++++++++++ recommonmark/__init__.py | 2 +- setup.cfg | 11 ++++++++++- 3 files changed, 42 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3415e68..8b97b39 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,34 @@ + +Version 0.6.0 +------------- + +Date: 2019-08-09 + +- [@RaptorCZ](http://github.com/RaptorCZ): Process linebreaks and + convert them to br element. + ([\#162](https://github.com/readthedocs/recommonmark/pull/162)) +- [@gibfahn](http://github.com/gibfahn): Remove URL quoting from refs + before passing to Sphinx + ([\#158](https://github.com/readthedocs/recommonmark/pull/158)) +- [@dandersson](http://github.com/dandersson): Use image description + text as \"alt\", drop title + ([\#150](https://github.com/readthedocs/recommonmark/pull/150)) +- [@annegentle](http://github.com/annegentle): Clarify the specifics + of Auto Toc Tree + ([\#149](https://github.com/readthedocs/recommonmark/pull/149)) +- [@loganrosen](http://github.com/loganrosen): Bump dependency on + commonmark to \>= 0.8.1 + ([\#147](https://github.com/readthedocs/recommonmark/pull/147)) +- [@codejamninja](http://github.com/codejamninja): Use official + gitignore template + ([\#140](https://github.com/readthedocs/recommonmark/pull/140)) +- [@dotlambda](http://github.com/dotlambda): Include all test files in + PyPI tarball + ([\#128](https://github.com/readthedocs/recommonmark/pull/128)) +- [@tk0miya](http://github.com/tk0miya): Register a parser class using + new Sphinx API; add\_source\_suffix + ([\#113](https://github.com/readthedocs/recommonmark/pull/113)) + ## Changelog ## 0.4.0 (in development) diff --git a/recommonmark/__init__.py b/recommonmark/__init__.py index db27ab2..e912764 100644 --- a/recommonmark/__init__.py +++ b/recommonmark/__init__.py @@ -1,6 +1,6 @@ """Docutils CommonMark parser""" -__version__ = '0.5.0' +__version__ = '0.6.0' def setup(app): diff --git a/setup.cfg b/setup.cfg index 3c6e79c..184f13c 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,2 +1,11 @@ [bdist_wheel] -universal=1 +universal = 1 + +[metadata] +name = recommonmark +version = 0.6.0 + +[tool:release] +github_owner = readthedocs +github_repo = recommonmark + From 7577703567cab27a15937305e1397e08aa125de4 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Fri, 9 Aug 2019 11:30:02 -0700 Subject: [PATCH 2/3] Small cleanup --- docs/auto_structify.md | 14 +++++++++++++- docs/conf.py | 5 +---- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/auto_structify.md b/docs/auto_structify.md index a428bd3..52eba2e 100644 --- a/docs/auto_structify.md +++ b/docs/auto_structify.md @@ -1,5 +1,6 @@ AutoStructify Component ======================= + AutoStructify is a component in recommonmark that takes a parsed docutil AST by `CommonMarkParser`, and transform it to another AST that introduces some of more. This enables additional features of recommonmark syntax, to introduce more structure into the final generated document. @@ -7,6 +8,7 @@ of recommonmark syntax, to introduce more structure into the final generated doc Configuring AutoStructify ------------------------- + The behavior of AutoStructify can be configured via a dict in document setting. In sphinx, you can configure it by `conf.py`. The following snippet is what is actually used to generate this document, see full code at [conf.py](conf.py). @@ -21,9 +23,11 @@ def setup(app): app.add_transform(AutoStructify) ``` + All the features are by default enabled ***List of options*** + * __enable_auto_toc_tree__: whether enable [Auto Toc Tree](#auto-toc-tree) feature. * __auto_toc_tree_section__: when enabled, [Auto Toc Tree](#auto-toc-tree) will only be enabled on section that matches the title. * __enable_auto_doc_ref__: whether enable [Auto Doc Ref](#auto-doc-ref) feature. **Deprecated** @@ -34,6 +38,7 @@ All the features are by default enabled Auto Toc Tree ------------- + One of important command in tools like sphinx is `toctree`. This is a command to generate table of contents and tell sphinx about the structure of the documents. In markdown, usually we manually list of contents by a bullet list of url reference to the other documents. @@ -44,7 +49,9 @@ AutoStructify transforms bullet list of document URLs like this * [Title1](doc1.md) * [Title2](doc2.md) ``` + to the AST of this following reStructuredText code + ```rst .. toctree:: :maxdepth: 1 @@ -52,6 +59,7 @@ to the AST of this following reStructuredText code doc1 doc2 ``` + You can also find the usage of this feature in `index.md` of this document. Auto Doc Ref @@ -66,10 +74,13 @@ Auto Doc Ref It is common to refer to another document page in one document. We usually use reference to do that. AutoStructify will translate these reference block into a structured document reference. For example + ``` [API Reference](api_ref.md) ``` + will be translated to the AST of following reStructuredText code + ``` :doc:`API Reference ` ``` @@ -77,6 +88,7 @@ And it will be rendered as [API Reference](api_ref) URL Resolver ------------ + Sometimes in a markdown, we want to refer to the code in the same repo. This can usually be done by a reference by reference path. However, since the generated document is hosted elsewhere, the relative path may not work in generated document site. URL resolver is introduced to solve this problem. @@ -87,9 +99,9 @@ So `[parser code](../recommonmark/parser.py)` will be translated into [parser co Note that the reference to the internal document will not be passed to url resolver, and will be linked to the internal document pages correctly, see [Auto Doc Ref](#auto-doc-ref). - Codeblock Extensions -------------------- + In markdown, you can write codeblocks fenced by (at least) three backticks (```` ``` ````). The following is an example of codeblock. diff --git a/docs/conf.py b/docs/conf.py index 574f201..5c2f8c1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,12 +21,8 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath('..')) import recommonmark -from recommonmark.parser import CommonMarkParser from recommonmark.transform import AutoStructify -source_parsers = { - '.md': CommonMarkParser -} source_suffix = ['.rst', '.md'] @@ -42,6 +38,7 @@ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.mathjax', + 'recommonmark', ] # Add any paths that contain templates here, relative to this directory. From cdd25e33f38071588e932720d99df203a95cd380 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Fri, 9 Aug 2019 11:30:59 -0700 Subject: [PATCH 3/3] Add node_modules to gitignore --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 1e2af61..9d0a2a9 100644 --- a/.gitignore +++ b/.gitignore @@ -28,6 +28,7 @@ share/python-wheels/ .installed.cfg *.egg MANIFEST +node_modules/ # PyInstaller # Usually these files are written by a python script from a template