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
Basically this extension will replace
README.rst by a proper
activate the support of Markdown files in Sphinx.
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
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
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
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:
Please also check PyScaffold's contribution guidelines.
This project has been set up using PyScaffold 4.0. For details and usage information on PyScaffold see https://pyscaffold.org/.