PyScaffold extension which uses Markdown instead of reStructuredText
Project description
pyscaffoldext-markdown
PyScaffold extension which replaces reStructuredText formatted files by Markdown format except for Sphinx-related files.
Usage
Just install this package with either pip install pyscaffoldext-markdown or conda install -c conda-forge pyscaffoldext-markdown
and note that putup -h shows a new option --markdown.
Basically this extension will replace README.rst by a proper README.md and
activate the support of Markdown files in Sphinx.
Limitations
Due to limitations of the Markdown syntax compared to reStructuredText,
it is necessary to use symbolic links (and some reStructuredText files) to
avoid keeping multiple copies of files (such as CHANGELOG.md) meant to be
placed at the root of the repository but included in the documentation
generated by Sphinx. If you are a Windows user please make sure to configure
your system accordingly. The following references might be helpful:
Symbolic links on Windows
- http://github.com/git-for-windows/git/wiki/Symbolic-Links
- https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10/
- https://docs.microsoft.com/en-us/windows/win32/fileio/creating-symbolic-links
Markdown limitations
- https://github.com/readthedocs/recommonmark/issues/191
- https://github.com/sphinx-doc/sphinx/issues/701
- https://github.com/sphinx-doc/sphinx/pull/7739
Windows users that still face problems after configuring their systems for symbolic links might want to attempt WSL or decide to stick with reStructuredText for (problematic) parts of their documentation files.
Building and Releasing
By default, the tox configuration generated by PyScaffold is compatible with Markdown (as implemented in this extension). This means that (after installing tox with pip or pipx) you can run:
tox -e docs # to build your documentation
tox -e build # to build your package distribution
tox -e publish # to test your project uploads correctly in test.pypi.org
tox -e publish -- --repository pypi # to release your package to PyPI
tox -av # to list all the tasks available
Please remember that the command python setup.py release is no longer
recommended, so if you don't like tox, please consider using
Sphinx and twine directly:
python -m pip install -U pip setuptools wheel sphinx twine
python setup.py bdist_wheel # to build your package distributions
make -C docs html # to build your docs
twine upload dist/* # to release your package to PyPI
Making Changes & Contributing
This project uses pre-commit, please make sure to install it before making any changes:
pip install pre-commit
cd pyscaffoldext-markdown
pre-commit install
It is a good idea to update the hooks to the latest version:
pre-commit autoupdate
Please also check PyScaffold's contribution guidelines.
Note
This project has been set up using PyScaffold 4.0. For details and usage information on PyScaffold see https://pyscaffold.org/.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file pyscaffoldext-markdown-0.4.1.tar.gz.
File metadata
- Download URL: pyscaffoldext-markdown-0.4.1.tar.gz
- Upload date:
- Size: 25.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.1 importlib_metadata/3.7.3 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.59.0 CPython/3.7.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 6959e5a3ebf2a7a2b1226a4071ecbb61e3e89358c68d1dcf3678f31fa1cd14ce |
|
| MD5 | e87c54829eace9420ab1c5aa50c3c142 |
|
| BLAKE2b-256 | 02c69639d183a558c89e82a3211a7b79d2bd70208dce39071e85d337dc40ce86 |
File details
Details for the file pyscaffoldext_markdown-0.4.1-py2.py3-none-any.whl.
File metadata
- Download URL: pyscaffoldext_markdown-0.4.1-py2.py3-none-any.whl
- Upload date:
- Size: 11.4 kB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.1 importlib_metadata/3.7.3 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.59.0 CPython/3.7.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | fbfa211e9a0ad8b7bd9fe39189726d9557c52c248d0cbca5d366cefb5c1392df |
|
| MD5 | bfbb278835280aa95a6f07b01ce29fe1 |
|
| BLAKE2b-256 | d0c0d9298bae2af0c5dd7eb2d1f8af1c54dc8f279e326b671688091bcbcc4c51 |
