Skip to content

Commit 9a1c275

Browse files
jambonrosejambonrose
authored
📚 Add documentation (#44)
* 📚 Add badge for Github release number * 🐛 Replace coverage badge with codecov badge * ➕ Install Sphinx and related tools * 📚 Quickstart Sphinx documentation * 🔧🚀 Include docs during bumpversion upgrade * 🔧📚 Use ReadTheDocs Sphinx theme for docs * 👷‍♀️ Build docs in Tox tests * 🔧📚 Configure Read the Docs builds * 📚 Write documentation (mimic's subscript project) * 🚀 Update Manifest with docs * 📚 Fix typo in History * 👷‍♀️ Install pytest-travis-fold for CI
1 parent 36382ad commit 9a1c275

21 files changed

+633
-56
lines changed

‎.bumpversion.cfg

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,5 @@ tag = False
66
[bumpversion:file:setup.py]
77
search = version="{current_version}"
88
replace = version="{new_version}"
9+
10+
[bumpversion:file:docs/conf.py]

‎.readthedocs.yml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
requirements_file: requirements/doc_requirements.txt
2+
build:
3+
image: latest
4+
python:
5+
version: 3.6

‎.travis.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ matrix:
3434
install:
3535
- if [[ `python -V | grep -c -e 3.7` -eq 1 && "$MD_VERSION" == '3.0' ]]; then pip install -r requirements/lint_requirements.txt ; fi
3636
- pip install -r requirements/test_requirements.txt
37-
- pip install codecov
37+
- pip install codecov pytest-travis-fold
3838
- pip install -q "Markdown>=$MD_VERSION,<$MD_NEXT"
3939
- python setup.py develop
4040
before_script:

‎AUTHORS.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Credits
55
Development Lead
66
----------------
77

8-
* Andrew Pinkham <http://AndrewsForge.com>
8+
* Andrew Pinkham <http://andrewsforge.com/>
99

1010
Contributors
1111
------------

‎CONTRIBUTING.rst

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
.. highlight:: console
2+
3+
============
4+
Contributing
5+
============
6+
7+
Contributions are welcome, and they are greatly appreciated! Every
8+
little bit helps, and credit will always be given.
9+
10+
You can contribute in many ways:
11+
12+
Types of Contributions
13+
----------------------
14+
15+
Report Bugs
16+
~~~~~~~~~~~
17+
18+
Report bugs on `Github issues`_.
19+
20+
If you are reporting a bug, please follow the guidelines shown to you
21+
while reporting the bug
22+
23+
Fix Bugs and Support Others
24+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
25+
26+
Look through the open `GitHub issues`_. Anything tagged with
27+
"help wanted" is open to whoever wants to implement it. Anything tagged
28+
with "support" means someone needs help, and you may be the person to
29+
help them!
30+
31+
Implement Features
32+
~~~~~~~~~~~~~~~~~~
33+
34+
Look through the `GitHub issues`_ for features. Anything tagged with
35+
"enhancement" and "help wanted" is open to whoever wants to implement it.
36+
37+
Write Documentation
38+
~~~~~~~~~~~~~~~~~~~
39+
40+
Markdown Superscript could always use more documentation, whether as part
41+
of the official Markdown Superscript docs, in docstrings, or even on the
42+
web in blog posts, articles, and such.
43+
44+
Submit Feedback
45+
~~~~~~~~~~~~~~~
46+
47+
The best way to send feedback is to `file an issue on Github`_.
48+
49+
If you are proposing a feature:
50+
51+
* Explain in detail how it would work.
52+
53+
* Keep the scope as narrow as possible, to make it easier to implement.
54+
55+
* Remember that this is a volunteer-driven project, and that contributions
56+
are welcome :)
57+
58+
.. _`file an issue on Github`:
59+
.. _`Github Issues`: https://github.com/jambonrose/markdown_superscript_extension/issues
60+
61+
Get Started!
62+
------------
63+
64+
Ready to contribute? Here's how to set up ``markdown_superscript_extension``
65+
for local development.
66+
67+
1. Fork the ``markdown_superscript_extension`` repository on `GitHub`_.
68+
69+
.. _`Github`: https://github.com/jambonrose/markdown_superscript_extension
70+
71+
2. Create a directory for your project, and then create a virtual
72+
environment. If you new to virtual environments, `RealPython's
73+
Virtualenv Primer`_ is for you! The code below demonstrates how to
74+
create a virtual project with `Virtualenvwrapper`_ ::
75+
76+
$ mkproject markdown_superscript_extension
77+
78+
.. _`RealPython's Virtualenv Primer`: https://realpython.com/python-virtual-environments-a-primer/
79+
.. _Virtualenvwrapper: https://virtualenvwrapper.readthedocs.io/en/latest/
80+
81+
3. Clone your fork locally into your new project. ::
82+
83+
$ git clone [email protected]:YOUR_USERNAME_HERE/markdown_superscript_extension.git .
84+
85+
4. Install the necessary dependencies using pip. If you don't have
86+
`pip`_ installed, the `Python installation guide`_ can guide you
87+
through the process. ::
88+
89+
$ pip install -r requirements/dev_requirements.txt
90+
$ pip install -r requirements/lint_requirements.txt
91+
$ pip install -r requirements/test_requirements.txt
92+
$ python setup.py develop
93+
94+
.. _pip: https://pip.pypa.io/en/stable/
95+
.. _Python installation guide: https://docs.python-guide.org/starting/installation/
96+
97+
5. Create a branch for local development and begin to make changes! ::
98+
99+
$ git checkout -b name-of-your-bugfix-or-feature
100+
101+
6. Make small, targeted changes. Commit often, and write clear messages!
102+
Remember that this is a volunteer-drive project. The clearer your
103+
intent and your changes, the easier it will be for us to review your
104+
work. ::
105+
106+
$ git add .
107+
$ git commit -m "Your detailed description of your changes."
108+
109+
5. The project is configured to use `pre-commit`_. If you'd like to have
110+
each commit checked as you make it, install it as a hook for your
111+
repository, as demonstrated below. ::
112+
113+
$ pre-commit install
114+
115+
.. _`pre-commit`: https://pre-commit.com/
116+
117+
6. When you're done making changes, check that your changes pass the
118+
test suite. If you're not using `pre-commit`_, you will also need to
119+
use the linters and auto-formatters. ::
120+
121+
$ make test # or python setup.py test
122+
$ # linters below
123+
$ flake8 mdx_superscript.py tests
124+
$ isort --verbose --check-only --diff mdx_superscript.py
125+
$ black mdx_superscript.py tests
126+
127+
7. If you have Python 2.7, 3.4, 3.5, 3.6, and 3.7 installed, as well as
128+
both PyPy and PyPy3, you may use ``tox`` to run all of the tests in
129+
all of the supported environments. ::
130+
131+
$ tox
132+
133+
8. Once you've made the changes you want, push your branch to GitHub. ::
134+
135+
$ git push -u origin name-of-your-bugfix-or-feature
136+
137+
9. Submit a pull request from your new branch to the original repository
138+
through the GitHub website.
139+
140+
10. 🎉 Thank you for taking the time to read this and for your potential
141+
contributions!
142+
143+
Pull Request Guidelines
144+
-----------------------
145+
146+
Before you submit a pull request, check that it meets these guidelines:
147+
148+
1. If a bug-fix or new feature, the pull request should include tests.
149+
150+
2. If the pull request adds functionality, the docs should be updated.
151+
152+
3. The pull request should work for all supported Python versions. If
153+
you are unable to run ``tox`` locally, the CI will run the test suite
154+
for you (but please consider running the suite beforehand).
155+
156+
.. _`Travis CI`: https://travis-ci.org/jambonrose/markdown_superscript_extension/

‎HISTORY.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Next Version!
2525
- Drop Support For:
2626
- Python 2.6 (EOL 2013)
2727
- Python 3.2 (EOL 2016)
28-
- Python-Markdown 2.4 (Superceded in 2014)
28+
- Python-Markdown 2.4 (Superseded in 2014)
2929
- Fix Issue #2 - Setup.py errors; Description.rst missing
3030

3131

‎MANIFEST.in

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,17 @@ exclude .ignore
55
exclude .isort.cfg
66
exclude .pre-commit-config.yaml
77
exclude .pyup.yml
8+
exclude .readthedocs.yml
89
exclude .travis.yml
910
exclude Makefile
1011
exclude tox.ini
1112
include AUTHORS.rst
13+
include CONTRIBUTING.rst
1214
include HISTORY.rst
1315
include LICENSE
1416
include pyproject.toml
1517
include README.rst
1618
include setup.cfg
19+
recursive-include docs *.txt *.rst conf.py Makefile make.bat
1720
recursive-include requirements *.txt
1821
recursive-include tests *.py

‎README.rst

Lines changed: 26 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,29 @@
1-
Latest Release: |Version|
1+
Latest Release: |Version| |Tag|
2+
3+
Documentation: |Docs|
24

35
Compatibility: |Implementation| |Python| |License|
46

57
Tests: |Build| |Coverage| |PyUp| |Requirements|
68

79
.. |Version| image:: http://img.shields.io/pypi/v/MarkdownSuperscript.svg
8-
:target: https://pypi.python.org/pypi/MarkdownSuperscript/
10+
:target: https://pypi.org/project/MarkdownSuperscript/
911
:alt: PyPI Version
1012

13+
.. |Tag| image:: https://img.shields.io/github/tag/jambonrose/markdown_superscript_extension.svg
14+
:target: https://github.com/jambonrose/markdown_superscript_extension/releases
15+
:alt: Github Tag
16+
17+
.. |Docs| image:: https://readthedocs.org/projects/markdown_superscript_extension/badge/?version=latest
18+
:target: http://markdown_superscript_extension.readthedocs.io/en/latest/?badge=latest
19+
:alt: Documentation Status
1120

1221
.. |Implementation| image:: https://img.shields.io/pypi/implementation/MarkdownSuperscript.svg
13-
:target: https://pypi.python.org/pypi/MarkdownSuperscript/
22+
:target: https://pypi.org/project/MarkdownSuperscript/
1423
:alt: Python Implementation Support
1524

1625
.. |Python| image:: https://img.shields.io/pypi/pyversions/MarkdownSuperscript.svg
17-
:target: https://pypi.python.org/pypi/MarkdownSuperscript/
26+
:target: https://pypi.org/project/MarkdownSuperscript/
1827
:alt: Python Support
1928

2029
.. |License| image:: http://img.shields.io/pypi/l/MarkdownSuperscript.svg
@@ -25,8 +34,8 @@ Tests: |Build| |Coverage| |PyUp| |Requirements|
2534
:target: https://travis-ci.org/jambonrose/markdown_superscript_extension
2635
:alt: Build Status
2736

28-
.. |Coverage| image:: https://img.shields.io/coveralls/jambonrose/markdown_superscript_extension.svg
29-
:target: https://coveralls.io/r/jambonrose/markdown_superscript_extension
37+
.. |Coverage| image:: https://codecov.io/gh/jambonrose/markdown_superscript_extension/branch/development/graph/badge.svg
38+
   :target: https://codecov.io/gh/jambonrose/markdown_superscript_extension
3039
:alt: Coverage Status
3140

3241
.. |PyUp| image:: https://pyup.io/repos/github/jambonrose/markdown_superscript_extension/shield.svg
@@ -37,70 +46,34 @@ Tests: |Build| |Coverage| |PyUp| |Requirements|
3746
:target: https://requires.io/github/jambonrose/markdown_superscript_extension/requirements/?branch=development
3847
:alt: Requirements Status
3948

49+
4050
=======
4151
Read Me
4252
=======
4353

54+
.. start-pypi-description
55+
4456
An extension to the `Python Markdown`_ project which adds the ability to
4557
superscript text. To do so, the character :code:`^` becomes a Markdown
4658
tag for text meant to be superscripted, and is replaced with the HTML
4759
:code:`sup` tag.
4860

49-
For example, given the text: ::
61+
For example, the extension transforms the text directly below into the
62+
HTML shown after it.
5063

51-
2^10^ is 1024.
64+
.. code-block:: text
5265
53-
… using Markdown with this extension will output:
66+
2^10^ is 1024.
5467
55-
.. code :: html
68+
.. code-block:: html
5669

5770
<p>2<sup>10</sup> is 1024.</p>
5871

5972
This project is provided under the `Simplified (2 Clause) BSD license`_,
6073
provided in full in the LICENSE file.
6174

75+
Please read `the documentation`_ for more information.
76+
6277
.. _`Python Markdown`: https://pypi.python.org/pypi/Markdown
6378
.. _`Simplified (2 Clause) BSD license`: http://choosealicense.com/licenses/bsd-2-clause/
64-
65-
Installation
66-
------------
67-
68-
Dependencies:
69-
70-
- Python 2.7, 3.3+
71-
72-
- Markdown 2.5+
73-
(Tested against latest patch version of Markdown 2.5, 2.6, 3.0)
74-
75-
To install the latest stable release (recommended):
76-
77-
.. code :: bash
78-
79-
pip install MarkdownSuperscript
80-
81-
To install the development version:
82-
83-
.. code :: bash
84-
85-
pip install git+git://github.com/jambonrose/markdown_superscript_extension.git
86-
87-
Basic Usage
88-
-----------
89-
90-
Python
91-
^^^^^^
92-
93-
.. code :: pycon
94-
95-
>>> from markdown import markdown
96-
>>> text = "2^10^ is 1024."
97-
>>> markdown(text, extensions=['mdx_superscript'])
98-
'<p>2<sup>10</sup> is 1024.</p>'
99-
100-
Command Line
101-
^^^^^^^^^^^^
102-
103-
.. code :: bash
104-
105-
$ echo '2^10^ is 1024.' > text.md
106-
$ python -m markdown -o html5 -x 'mdx_superscript' -f text.html text.md
79+
.. _`the documentation`: https://markdown-superscript-extension.readthedocs.io/en/latest/

‎docs/Makefile

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SOURCEDIR = .
8+
BUILDDIR = _build
9+
10+
# Put it first so that "make" without argument is like "make help".
11+
help:
12+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
13+
14+
.PHONY: help Makefile
15+
16+
# Catch-all target: route all unknown targets to Sphinx using the new
17+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
18+
%: Makefile
19+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/authors.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. include:: ../AUTHORS.rst

0 commit comments

Comments
 (0)