convert docs to markdown

craigahobbs · Apr 3, 2024 · 7156801 · 7156801
1 parent 7fe874b
commit 7156801
Show file tree

Hide file tree

Showing 38 changed files with 182 additions and 258 deletions.
diff --git a/template/Makefile b/template/Makefile
@@ -12,12 +12,18 @@ WGET_CMD = if which wget; then wget -q -c $(1); else curl -f -Os $(1); fi
 $(eval $(call WGET, https://raw.githubusercontent.com/craigahobbs/python-build/main/Makefile.base))
 $(eval $(call WGET, https://raw.githubusercontent.com/craigahobbs/python-build/main/pylintrc))
 {% if noapi is not defined or not noapi %}
+
 # Sphinx documentation directory
 SPHINX_DOC := doc
+
+# Development dependencies
+TESTS_REQUIRE := bare-script myst-parser
 {% endif %}
+
 # Include python-build
 include Makefile.base
 
+
 clean:
 	rm -rf Makefile.base pylintrc{% if noapi is defined and noapi %}
 

diff --git a/template/README.md b/template/README.md
@@ -10,7 +10,10 @@ Coming soon!
 
 ## Links
 
-- [Source code](https://github.com/{{github}}/{{package}})
+{% if noapi is not defined or not noapi -%}
+- [API Documentation](https://{{github}}.github.io/{{package}}/)
+{% endif -%}
+ - [Source code](https://github.com/{{github}}/{{package}})
 
 
 ## Development

diff --git a/template/README.rst b/template/README.rst
diff --git a/template/doc/conf.py b/template/doc/conf.py
@@ -38,7 +38,8 @@
     'sphinx.ext.autosectionlabel',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
-    'sphinx.ext.githubpages'
+    'sphinx.ext.githubpages',
+    'myst_parser'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/template/doc/index.md b/template/doc/index.md
@@ -0,0 +1,9 @@
+~~~ {include} ../README.md
+~~~
+
+~~~ {toctree}
+:maxdepth: 2
+:hidden:
+
+reference
+~~~
diff --git a/template/doc/index.rst b/template/doc/index.rst
diff --git a/template/doc/reference.rst → template/doc/reference.md b/template/doc/reference.rst → template/doc/reference.md
@@ -1,8 +1,8 @@
-Reference
-=========
+# Reference
 
 
-sum_numbers
------------
+## sum_numbers
 
+~~~ {eval-rst}
 .. autofunction:: {{ package | replace('-', '_') }}.sum_numbers
+~~~
diff --git a/template/python-template.txt b/template/python-template.txt
@@ -3,12 +3,10 @@
 
 {# Delete the package API, if requested #}
 {% if noapi is defined and noapi %}
-  {% template_specialize_rename 'README.rst' %}
   {% template_specialize_rename 'doc' %}
   {% template_specialize_rename 'src/package-name/package_name.py' %}
   {% template_specialize_rename 'src/tests/test_package_name.py' %}
 {% else %}
-  {% template_specialize_rename 'README.md' %}
   {% template_specialize_rename 'src/package-name/package_name.py', package.replace('-', '_') + '.py' %}
   {% template_specialize_rename 'src/tests/test_package_name.py', 'test_' + package.replace('-', '_') + '.py' %}
 {% endif %}

diff --git a/template/setup.cfg b/template/setup.cfg
@@ -6,13 +6,8 @@ author = {{name}}
 author_email = {{email}}
 license = MIT
 description = {{package}}
-{% if noapi is defined and noapi -%}
 long_description = file:README.md
 long_description_content_type = text/markdown
-{% else -%}
-long_description = file:README.rst
-long_description_content_type = text/x-rst
-{% endif -%}
 keywords = {{package}}
 classifiers =
     Development Status :: 5 - Production/Stable

diff --git a/test-expected/noapi-0-nomain-0/Makefile b/test-expected/noapi-0-nomain-0/Makefile
@@ -12,11 +12,17 @@ WGET_CMD = if which wget; then wget -q -c $(1); else curl -f -Os $(1); fi
 $(eval $(call WGET, https://raw.githubusercontent.com/craigahobbs/python-build/main/Makefile.base))
 $(eval $(call WGET, https://raw.githubusercontent.com/craigahobbs/python-build/main/pylintrc))
 
+
 # Sphinx documentation directory
 SPHINX_DOC := doc
 
+# Development dependencies
+TESTS_REQUIRE := bare-script myst-parser
+
+
 # Include python-build
 include Makefile.base
 
+
 clean:
 	rm -rf Makefile.base pylintrc
diff --git a/test-expected/noapi-0-nomain-0/README.md b/test-expected/noapi-0-nomain-0/README.md
@@ -0,0 +1,24 @@
+# my-package
+
+[![PyPI - Status](https://img.shields.io/pypi/status/my-package)](https://pypi.org/project/my-package/)
+[![PyPI](https://img.shields.io/pypi/v/my-package)](https://pypi.org/project/my-package/)
+[![GitHub](https://img.shields.io/github/license/johndoe/my-package)](https://github.com/johndoe/my-package/blob/main/LICENSE)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/my-package)](https://pypi.org/project/my-package/)
+
+Coming soon!
+
+
+## Links
+
+- [API Documentation](https://johndoe.github.io/my-package/)
+- [Source code](https://github.com/johndoe/my-package)
+
+
+## Development
+
+This package is developed using [python-build](https://github.com/craigahobbs/python-build#readme).
+It was started using [python-template](https://github.com/craigahobbs/python-template#readme) as follows:
+
+~~~
+template-specialize python-template/template/ my-package/ -k package my-package -k name 'John Doe' -k email '[email protected]' -k github 'johndoe'
+~~~
diff --git a/test-expected/noapi-0-nomain-0/README.rst b/test-expected/noapi-0-nomain-0/README.rst
diff --git a/test-expected/noapi-0-nomain-0/doc/conf.py b/test-expected/noapi-0-nomain-0/doc/conf.py
@@ -38,7 +38,8 @@
     'sphinx.ext.autosectionlabel',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
-    'sphinx.ext.githubpages'
+    'sphinx.ext.githubpages',
+    'myst_parser'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/test-expected/noapi-0-nomain-0/doc/index.md b/test-expected/noapi-0-nomain-0/doc/index.md
@@ -0,0 +1,9 @@
+~~~ {include} ../README.md
+~~~
+
+~~~ {toctree}
+:maxdepth: 2
+:hidden:
+
+reference
+~~~
diff --git a/test-expected/noapi-0-nomain-0/doc/index.rst b/test-expected/noapi-0-nomain-0/doc/index.rst
diff --git a/test-expected/noapi-0-nomain-0/doc/reference.md b/test-expected/noapi-0-nomain-0/doc/reference.md
@@ -0,0 +1,8 @@
+# Reference
+
+
+## sum_numbers
+
+~~~ {eval-rst}
+.. autofunction:: my_package.sum_numbers
+~~~
diff --git a/test-expected/noapi-0-nomain-0/doc/reference.rst b/test-expected/noapi-0-nomain-0/doc/reference.rst
diff --git a/test-expected/noapi-0-nomain-0/setup.cfg b/test-expected/noapi-0-nomain-0/setup.cfg
@@ -6,8 +6,8 @@ author = John Doe
 author_email = [email protected]
 license = MIT
 description = my-package
-long_description = file:README.rst
-long_description_content_type = text/x-rst
+long_description = file:README.md
+long_description_content_type = text/markdown
 keywords = my-package
 classifiers =
     Development Status :: 5 - Production/Stable

diff --git a/test-expected/noapi-nomain/Makefile b/test-expected/noapi-nomain/Makefile
@@ -12,9 +12,11 @@ WGET_CMD = if which wget; then wget -q -c $(1); else curl -f -Os $(1); fi
 $(eval $(call WGET, https://raw.githubusercontent.com/craigahobbs/python-build/main/Makefile.base))
 $(eval $(call WGET, https://raw.githubusercontent.com/craigahobbs/python-build/main/pylintrc))
 
+
 # Include python-build
 include Makefile.base
 
+
 clean:
 	rm -rf Makefile.base pylintrc
 

diff --git a/test-expected/noapi/Makefile b/test-expected/noapi/Makefile
@@ -12,9 +12,11 @@ WGET_CMD = if which wget; then wget -q -c $(1); else curl -f -Os $(1); fi
 $(eval $(call WGET, https://raw.githubusercontent.com/craigahobbs/python-build/main/Makefile.base))
 $(eval $(call WGET, https://raw.githubusercontent.com/craigahobbs/python-build/main/pylintrc))
 
+
 # Include python-build
 include Makefile.base
 
+
 clean:
 	rm -rf Makefile.base pylintrc
 

diff --git a/test-expected/nomain/Makefile b/test-expected/nomain/Makefile
@@ -12,11 +12,17 @@ WGET_CMD = if which wget; then wget -q -c $(1); else curl -f -Os $(1); fi
 $(eval $(call WGET, https://raw.githubusercontent.com/craigahobbs/python-build/main/Makefile.base))
 $(eval $(call WGET, https://raw.githubusercontent.com/craigahobbs/python-build/main/pylintrc))
 
+
 # Sphinx documentation directory
 SPHINX_DOC := doc
 
+# Development dependencies
+TESTS_REQUIRE := bare-script myst-parser
+
+
 # Include python-build
 include Makefile.base
 
+
 clean:
 	rm -rf Makefile.base pylintrc
diff --git a/test-expected/nomain/README.md b/test-expected/nomain/README.md
@@ -0,0 +1,24 @@
+# my-package
+
+[![PyPI - Status](https://img.shields.io/pypi/status/my-package)](https://pypi.org/project/my-package/)
+[![PyPI](https://img.shields.io/pypi/v/my-package)](https://pypi.org/project/my-package/)
+[![GitHub](https://img.shields.io/github/license/johndoe/my-package)](https://github.com/johndoe/my-package/blob/main/LICENSE)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/my-package)](https://pypi.org/project/my-package/)
+
+Coming soon!
+
+
+## Links
+
+- [API Documentation](https://johndoe.github.io/my-package/)
+- [Source code](https://github.com/johndoe/my-package)
+
+
+## Development
+
+This package is developed using [python-build](https://github.com/craigahobbs/python-build#readme).
+It was started using [python-template](https://github.com/craigahobbs/python-template#readme) as follows:
+
+~~~
+template-specialize python-template/template/ my-package/ -k package my-package -k name 'John Doe' -k email '[email protected]' -k github 'johndoe' -k nomain 1
+~~~