Development

Resources

Markdown:

• https://www.markdownguide.org/cheat-sheet
• https://commonmark.org/help/
• Main reference: https://daringfireball.net/projects/markdown/

Extensions:

• https://python-markdown.github.io/extensions/api/
• https://python-markdown.github.io/cli/

Get ready to install:

cd repo
pip3 uninstall yafg
pip3 uninstall caption

Install from GitHub:

pip3 install git+https://github.com/flywire/caption

or install from local source:

pip3 install -e E:\source\repos\caption

Check:

pip3 list -v | grep -E "caption|yafg"

Test it:

Create these files in the code folder:

mkdocs.yml
docs\index.md
docs\css\styles.css
docs\images\gplv3.png

The images path seems to conflict between mkdocs and running the extension from python. Run mkdocs from the code folder and python from the docs folder under it or change the image path as needed.

Run mkdocs serve from code folder and open http://127.0.0.1:8000/ in browser

• mkdocs gives nice output and generates index.html in a folder under your environment %TEMP% path
• it still requires extra css for the content types added

or test from code\docs folder:

• view index.html in text editor or browser as required
• for coloured code: https://python-markdown.github.io/extensions/code_hilite/#step-2-add-css-classes
• Note css style sheet example in https://github.com/flywire/caption/issues/3#issuecomment-660130402

Once you have the css files a reference can be generated in Windows like:

• echo ^<link rel="stylesheet" href="css/styles.css"^> > css.html & echo ^<link rel="stylesheet" href="css/extra.css"^> >> css.html

And a quick and dirty prepend like:

• (>nul copy /y css.html index.*) & python -m markdown -x caption -x extra -x codehilite index.md >> index.html

unittest

The test folder has unittest program(s) to test functionality. These tests are part of a CI system but can be run locally from the test folder:

python -m unittest -v test_caption.captionTestCase

Reference: https://docs.python.org/3/library/unittest.html

PyPI

Setup described at https://packaging.python.org/tutorials/packaging-projects/

• Generate distribution packages for the package from the same directory where setup.py is located with:

python setup.py sdist bdist_wheel

• Login to https://pypi.org
• Use twine upload dist/* to upload your package and enter your credentials for the account you registered on the real PyPI