Help Resources ============== Frequently Asked Questions -------------------------- Why another Markdown library? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The primary reason is performance. Most applications that work with Markdown are going to be interested in one thing and one thing only: generating HTML. For that, there are two performance advantages from offloading the task to C: - C is more efficient with CPU cycles and memory usage than Python - A bulk processing task like this can release CPython's `Global Interpreter Lock`_ while it is not running Python code (an advantage for multithreading) There are several C libraries for Markdown parsing, but I chose MD4C for a couple reasons: - It is one of the fastest Markdown parsing libraries out there (if not *the* fastest). - The tests for MD4C are thorough. The author has put a lot of care into avoiding non-linear parsing time (meaning good protection from DOS attacks) and uses modern techniques like coverage testing and fuzzing. This is quite important considering it will likely handle untrusted input. And since Python bindings for MD4C did not yet exist, I decided to create them. .. _Global Interpreter Lock: https://docs.python.org/3/glossary.html#term-global-interpreter-lock .. _why-source: Why is pip trying to build from source? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This means pip cannot find a suitable pre-built package. There can be any number of reasons for this: - If you are on Linux with Python 3.6, your version of pip may be too old. Try upgrading to 19.3 or newer. - You are using 32-bit Python on Windows. Try installing 64-bit Python. - You are on an M1 Mac. - You are running an esoteric Linux distribution or on an architecture other than amd64. - You are on an OS other than Windows, macOS, or Linux. Unfortunately, apart from the first two reasons, there is currently no way to avoid building from source (pre-built packages cannot currently be compiled for your platform). If you are getting errors during the install, make sure you have all the prerequisites (see :ref:`prerequisites`), then try again. Why do I see ``error: pkg-config probably not installed: ...`` when trying to install? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Pip is trying to build from source. See :ref:`why-source` If building from source is unavoidable, make sure you install all the prerequisites (see :ref:`prerequisites`), then try again. Why do I see ``pkgconfig.pkgconfig.PackageNotFoundError: md4c not found`` when trying to install? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Pip is trying to build from source. See :ref:`why-source` If building from source is unavoidable, make sure you install all the prerequisites (see :ref:`prerequisites`), then try again. Generating These Docs Locally ----------------------------- This documentation is generated with Sphinx_. With it installed and a local copy of the PyMD4C repository, you can generate your own local copy of the docs as follows:: cd docs/ make html Now, you can browse the docs by opening "_build/html/index.html" in the browser of your choice. .. _Sphinx: https://www.sphinx-doc.org/en/master/ Human Help ---------- If you find you need a bit of human help, feel free to post in the discussions_ tab on GitHub. I do my best to keep an eye on these and respond. Currently, there is no mailing list, IRC channel, Discord chat, or Stack Overflow tag. The project is not yet big enough to warrant them. .. _discussions: https://github.com/dominickpastore/pymd4c/discussions