================
sphinx-no-pragma
================
.. External references
.. _Sphinx: https://github.com/sphinx-doc/sphinx
.. _jsphinx: https://jsphinx.readthedocs.io/
.. _MyPy: https://mypy.readthedocs.io/
.. Internal references
.. _sphinx-no-pragma: https://github.com/barseghyanartur/sphinx-no-pragma/
.. _Read the Docs: http://sphinx-no-pragma.readthedocs.io/
.. _Demo: http://sphinx-no-pragma.readthedocs.io/en/latest/demo.html
.. _Contributor guidelines: https://sphinx-no-pragma.readthedocs.io/en/latest/contributor_guidelines.html
**Improve developer experience**:
- Write better docs.
- Do not repeat yourself.
- Assure code low-maintenance.
.. image:: https://img.shields.io/pypi/v/sphinx-no-pragma.svg
:target: https://pypi.python.org/pypi/sphinx-no-pragma.py
:alt: PyPI Version
.. image:: https://img.shields.io/pypi/pyversions/sphinx-no-pragma.svg
:target: https://pypi.python.org/pypi/sphinx-no-pragma/
:alt: Supported Python versions
.. image:: https://github.com/barseghyanartur/sphinx-no-pragma/actions/workflows/test.yml/badge.svg?branch=main
:target: https://github.com/barseghyanartur/sphinx-no-pragma/actions
:alt: Build Status
.. image:: https://readthedocs.org/projects/sphinx-no-pragma/badge/?version=latest
:target: http://sphinx-no-pragma.readthedocs.io
:alt: Documentation Status
.. image:: https://img.shields.io/badge/license-MIT-blue.svg
:target: https://github.com/barseghyanartur/sphinx-no-pragma/#License
:alt: MIT
.. image:: https://coveralls.io/repos/github/barseghyanartur/sphinx-no-pragma/badge.svg?branch=main&service=github
:target: https://coveralls.io/github/barseghyanartur/sphinx-no-pragma?branch=main
:alt: Coverage
**TL;DR**
`sphinx-no-pragma`_ is a `Sphinx`_ extension for stripping pragma comments
from source code used in documentation.
If that's all you need to know to move forward, jump right to the
`installation`_. Otherwise, read further.
----
Some say, "documentation is the king". Others argue - "no, demos are". While
some say, "testing is everything!" and yet there will be someone else who
will jump in with "write clean code! black, isort, mypy and ruff everywhere!"
And yet there's you, who want to be good and write a better package, because
there's a generic problem that needs to be solved, and you know how, you want
to share it with the world. You also want to assure or at least make an effort
in making your project developer friendly, attractive for making contributions,
which eventually leads to continuous improvement and make it live long(er).
So, combining the best practices, you:
- Introduce examples in your repository to make it easier to start with.
- Write awesome docs with usage examples (by eventually repeating yourself,
copying things from your actual code examples).
- Write tests for your code. Then you realize it's good to test the examples
too. Eventually, you have now almost the same code in 3 places: tests,
examples and docs.
- Introduce linters and `MyPy`_.
Then you invest your time in making sure all your code looks correct and fix
the never-ending `MyPy`_ issues.
Then you need to make a small change, which unfortunately, among other,
requires altering the examples code. You need to change the examples, the
docs, the tests and the examples tests. However, you also need to push the
change quickly. As many times before, you skip documentation update,
leaving it for "another time".
By that time you discover that code maintenance is a hell. You fix everything,
tests pass you're happy to push, by then `MyPy`_ starts to nag about issues
you have no idea how to solve and by that moment you don't care about them.
You're sick of it and start using pragma comments to silence the errors,
leaving the fix for another day. Your maintenance work involves a lot of
copy-pasting from one place to another (examples, tests, documentation).
Does this sound familiar?
----
What if I tell you that actually a couple of steps can be taken out.
Namely, that you can use your example code directly in your documentation,
using ``.. literalinclude::`` directive of `Sphinx`_. That part has already
been well covered in `jsphinx`_ project (JavaScript primarily). However,
what `jsphinx`_ didn't solve is presence of pragma comments in your
documentation. This project does take care of that part.
You don't need to choose or balance between readability, explainability and
low-maintenance.
Written by lazy developer for lazy developers to improve developer experience
in writing low-maintenance code.
Features
========
- Accurately stips out pragma comments from your source code that you include
in your documentation.
Prerequisites
=============
Python 3.8+
Installation
============
.. code-block:: sh
pip install sphinx-no-pragma
Documentation
=============
- Documentation is available on `Read the Docs`_.
- For guidelines on contributing check the `Contributor guidelines`_.
Usage example
=============
In order to move forward, you first need to get educate yourself a little on
`Sphinx`_'s directives. Namely the ``.. literalinclude::`` and ``:download:``.
For that, first read the `jsphinx`_ documentation.
But there might be a little problem with that. Of course you might be lucky and
have zero pragma comments in your code (no ``# noqa``,
no ``# type: ignore``, etc). But more often, you get at least a couple of
these. Your perfectionist nature doesn't easily allow you to let them be
part of your concise, beautiful documentation. Cursing me for earlier
advices, you start to replace your DRY documentation part with copy-pasted
examples.
This is where this package jumps in. It simply is a `Sphinx`_ extension that
strips all pragma comments from your code that goes into documentation.
Sphinx configuration
--------------------
*Filename: docs/conf.py*
.. code-block:: python
extensions = [
# ... other extensions
"sphinx_no_pragma",
# ... other extensions
]
Code example
------------
*Filename: examples/example_1.py*
.. code-block:: python
from typing import Any, Optional
class ThirdPartyLibrary:
@staticmethod
def get_dynamic_object() -> Any:
# Returns an object whose type is not known at compile time
return "a string" # In reality, this could be any type
# Usage of the third-party library
obj = ThirdPartyLibrary.get_dynamic_object()
# Attempt to use the object as a string, even though its type is 'Any'
length = len(obj) # type: ignore
# Deliberately long line to violate PEP 8 line length rule, suppressed with noqa
print(f"The length of the object, a dynamically typed one, is just {length}") # noqa
Given that this is your code structure:
.. code-block:: text
├── examples
│ └── example_1.py
├── docs
│ ├── conf.py
│ ├── index.rst
│ ├── Makefile
│ ├── _static
│ │ └── example_1.py
│ └── usage.rst
├── LICENSE
├── Makefile
├── pyproject.toml
├── README.rst
└── sphinx_no_pragma.py
Either use ``html_extra_path = ["examples"]`` or make a symlink to
``examples/example_1.py`` from ``docs/_static``.
Then include it in your docs as follows:
*Filename: example.rst*
.. code-block:: rst
.. container:: jsphinx-download
.. literalinclude:: _static/example_1.py
:language: python
:lines: 1-
*See the full example*
:download:`here <_static/example_1.py>`
Now, rendered, your code will not contain `# type: ignore` or `# noqa` pragma
comments.
See the `demo`_. Click on the `See the full example here` link to see
the original code.
Tests
=====
Run the tests with unittest:
.. code-block:: sh
python -m unittest sphinx_no_pragma.py
Or pytest:
.. code-block:: sh
pytest
License
=======
MIT
Support
=======
For security issues contact me at the e-mail given in the `Author`_ section.
For overall issues, go to
`GitHub <https://github.com/barseghyanartur/sphinx-no-pragma/issues>`_.
Author
======
Artur Barseghyan <artur.barseghyan@gmail.com>
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-no-pragma",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "sphinx, documentation, pragma",
"author": null,
"author_email": "Artur Barseghyan <artur.barseghyan@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/1b/28/b8d15278f7dbb5f01aa7f136a109cf92b377def2472e0ae8cb54713ef2da/sphinx_no_pragma-0.1.1.tar.gz",
"platform": null,
"description": "================\nsphinx-no-pragma\n================\n.. External references\n\n.. _Sphinx: https://github.com/sphinx-doc/sphinx\n.. _jsphinx: https://jsphinx.readthedocs.io/\n.. _MyPy: https://mypy.readthedocs.io/\n\n.. Internal references\n\n.. _sphinx-no-pragma: https://github.com/barseghyanartur/sphinx-no-pragma/\n.. _Read the Docs: http://sphinx-no-pragma.readthedocs.io/\n.. _Demo: http://sphinx-no-pragma.readthedocs.io/en/latest/demo.html\n.. _Contributor guidelines: https://sphinx-no-pragma.readthedocs.io/en/latest/contributor_guidelines.html\n\n**Improve developer experience**:\n\n- Write better docs.\n- Do not repeat yourself.\n- Assure code low-maintenance.\n\n.. image:: https://img.shields.io/pypi/v/sphinx-no-pragma.svg\n :target: https://pypi.python.org/pypi/sphinx-no-pragma.py\n :alt: PyPI Version\n\n.. image:: https://img.shields.io/pypi/pyversions/sphinx-no-pragma.svg\n :target: https://pypi.python.org/pypi/sphinx-no-pragma/\n :alt: Supported Python versions\n\n.. image:: https://github.com/barseghyanartur/sphinx-no-pragma/actions/workflows/test.yml/badge.svg?branch=main\n :target: https://github.com/barseghyanartur/sphinx-no-pragma/actions\n :alt: Build Status\n\n.. image:: https://readthedocs.org/projects/sphinx-no-pragma/badge/?version=latest\n :target: http://sphinx-no-pragma.readthedocs.io\n :alt: Documentation Status\n\n.. image:: https://img.shields.io/badge/license-MIT-blue.svg\n :target: https://github.com/barseghyanartur/sphinx-no-pragma/#License\n :alt: MIT\n\n.. image:: https://coveralls.io/repos/github/barseghyanartur/sphinx-no-pragma/badge.svg?branch=main&service=github\n :target: https://coveralls.io/github/barseghyanartur/sphinx-no-pragma?branch=main\n :alt: Coverage\n\n**TL;DR**\n\n`sphinx-no-pragma`_ is a `Sphinx`_ extension for stripping pragma comments\nfrom source code used in documentation.\n\nIf that's all you need to know to move forward, jump right to the\n`installation`_. Otherwise, read further.\n\n----\n\nSome say, \"documentation is the king\". Others argue - \"no, demos are\". While\nsome say, \"testing is everything!\" and yet there will be someone else who\nwill jump in with \"write clean code! black, isort, mypy and ruff everywhere!\"\n\nAnd yet there's you, who want to be good and write a better package, because\nthere's a generic problem that needs to be solved, and you know how, you want\nto share it with the world. You also want to assure or at least make an effort\nin making your project developer friendly, attractive for making contributions,\nwhich eventually leads to continuous improvement and make it live long(er).\n\nSo, combining the best practices, you:\n\n- Introduce examples in your repository to make it easier to start with.\n- Write awesome docs with usage examples (by eventually repeating yourself,\n copying things from your actual code examples).\n- Write tests for your code. Then you realize it's good to test the examples\n too. Eventually, you have now almost the same code in 3 places: tests,\n examples and docs.\n- Introduce linters and `MyPy`_.\n\nThen you invest your time in making sure all your code looks correct and fix\nthe never-ending `MyPy`_ issues.\n\nThen you need to make a small change, which unfortunately, among other,\nrequires altering the examples code. You need to change the examples, the\ndocs, the tests and the examples tests. However, you also need to push the\nchange quickly. As many times before, you skip documentation update,\nleaving it for \"another time\".\n\nBy that time you discover that code maintenance is a hell. You fix everything,\ntests pass you're happy to push, by then `MyPy`_ starts to nag about issues\nyou have no idea how to solve and by that moment you don't care about them.\nYou're sick of it and start using pragma comments to silence the errors,\nleaving the fix for another day. Your maintenance work involves a lot of\ncopy-pasting from one place to another (examples, tests, documentation).\n\nDoes this sound familiar?\n\n----\n\nWhat if I tell you that actually a couple of steps can be taken out.\nNamely, that you can use your example code directly in your documentation,\nusing ``.. literalinclude::`` directive of `Sphinx`_. That part has already\nbeen well covered in `jsphinx`_ project (JavaScript primarily). However,\nwhat `jsphinx`_ didn't solve is presence of pragma comments in your\ndocumentation. This project does take care of that part.\nYou don't need to choose or balance between readability, explainability and\nlow-maintenance.\n\nWritten by lazy developer for lazy developers to improve developer experience\nin writing low-maintenance code.\n\nFeatures\n========\n- Accurately stips out pragma comments from your source code that you include\n in your documentation.\n\nPrerequisites\n=============\nPython 3.8+\n\nInstallation\n============\n.. code-block:: sh\n\n pip install sphinx-no-pragma\n\nDocumentation\n=============\n- Documentation is available on `Read the Docs`_.\n- For guidelines on contributing check the `Contributor guidelines`_.\n\nUsage example\n=============\nIn order to move forward, you first need to get educate yourself a little on\n`Sphinx`_'s directives. Namely the ``.. literalinclude::`` and ``:download:``.\nFor that, first read the `jsphinx`_ documentation.\n\nBut there might be a little problem with that. Of course you might be lucky and\nhave zero pragma comments in your code (no ``# noqa``,\nno ``# type: ignore``, etc). But more often, you get at least a couple of\nthese. Your perfectionist nature doesn't easily allow you to let them be\npart of your concise, beautiful documentation. Cursing me for earlier\nadvices, you start to replace your DRY documentation part with copy-pasted\nexamples.\n\nThis is where this package jumps in. It simply is a `Sphinx`_ extension that\nstrips all pragma comments from your code that goes into documentation.\n\nSphinx configuration\n--------------------\n*Filename: docs/conf.py*\n\n.. code-block:: python\n\n extensions = [\n # ... other extensions\n \"sphinx_no_pragma\",\n # ... other extensions\n ]\n\nCode example\n------------\n*Filename: examples/example_1.py*\n\n.. code-block:: python\n\n from typing import Any, Optional\n\n class ThirdPartyLibrary:\n @staticmethod\n def get_dynamic_object() -> Any:\n # Returns an object whose type is not known at compile time\n return \"a string\" # In reality, this could be any type\n\n\n # Usage of the third-party library\n obj = ThirdPartyLibrary.get_dynamic_object()\n\n # Attempt to use the object as a string, even though its type is 'Any'\n length = len(obj) # type: ignore\n\n # Deliberately long line to violate PEP 8 line length rule, suppressed with noqa\n print(f\"The length of the object, a dynamically typed one, is just {length}\") # noqa\n\nGiven that this is your code structure:\n\n.. code-block:: text\n\n \u251c\u2500\u2500 examples\n \u2502 \u2514\u2500\u2500 example_1.py\n \u251c\u2500\u2500 docs\n \u2502 \u251c\u2500\u2500 conf.py\n \u2502 \u251c\u2500\u2500 index.rst\n \u2502 \u251c\u2500\u2500 Makefile\n \u2502 \u251c\u2500\u2500 _static\n \u2502 \u2502 \u2514\u2500\u2500 example_1.py\n \u2502 \u2514\u2500\u2500 usage.rst\n \u251c\u2500\u2500 LICENSE\n \u251c\u2500\u2500 Makefile\n \u251c\u2500\u2500 pyproject.toml\n \u251c\u2500\u2500 README.rst\n \u2514\u2500\u2500 sphinx_no_pragma.py\n\nEither use ``html_extra_path = [\"examples\"]`` or make a symlink to\n``examples/example_1.py`` from ``docs/_static``.\n\nThen include it in your docs as follows:\n\n*Filename: example.rst*\n\n.. code-block:: rst\n\n .. container:: jsphinx-download\n\n .. literalinclude:: _static/example_1.py\n :language: python\n :lines: 1-\n\n *See the full example*\n :download:`here <_static/example_1.py>`\n\nNow, rendered, your code will not contain `# type: ignore` or `# noqa` pragma\ncomments.\n\nSee the `demo`_. Click on the `See the full example here` link to see\nthe original code.\n\nTests\n=====\nRun the tests with unittest:\n\n.. code-block:: sh\n\n python -m unittest sphinx_no_pragma.py\n\nOr pytest:\n\n.. code-block:: sh\n\n pytest\n\nLicense\n=======\nMIT\n\nSupport\n=======\nFor security issues contact me at the e-mail given in the `Author`_ section.\n\nFor overall issues, go to\n`GitHub <https://github.com/barseghyanartur/sphinx-no-pragma/issues>`_.\n\nAuthor\n======\nArtur Barseghyan <artur.barseghyan@gmail.com>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Strip pragmas from your docs.",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/barseghyanartur/sphinx-no-pragma/issues",
"Changelog": "https://sphinx-no-pragma.readthedocs.io/en/latest/changelog.html",
"Documentation": "https://sphinx-no-pragma.readthedocs.io/",
"Homepage": "https://github.com/barseghyanartur/sphinx-no-pragma/",
"Source Code": "https://github.com/barseghyanartur/sphinx-no-pragma/"
},
"split_keywords": [
"sphinx",
" documentation",
" pragma"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ee9b9041dcc34cdd7ce3e7ef08c35012fb25ab9e6b0da4166810a4ba8153663f",
"md5": "a410408c33def63560f2c28d35eeae0d",
"sha256": "a1762d3f934c317b61fde8629c15f5b02d76290c6865a26012e7dd158818c1ba"
},
"downloads": -1,
"filename": "sphinx_no_pragma-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a410408c33def63560f2c28d35eeae0d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6482,
"upload_time": "2024-07-04T21:05:32",
"upload_time_iso_8601": "2024-07-04T21:05:32.542091Z",
"url": "https://files.pythonhosted.org/packages/ee/9b/9041dcc34cdd7ce3e7ef08c35012fb25ab9e6b0da4166810a4ba8153663f/sphinx_no_pragma-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1b28b8d15278f7dbb5f01aa7f136a109cf92b377def2472e0ae8cb54713ef2da",
"md5": "ce229410082e97d68124fa451a9ea1e7",
"sha256": "7705899a36ccc8f94f2e7c9b78b4490fb246d8c29b603cfc4ede123a28f337a8"
},
"downloads": -1,
"filename": "sphinx_no_pragma-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "ce229410082e97d68124fa451a9ea1e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 23846,
"upload_time": "2024-07-04T21:05:46",
"upload_time_iso_8601": "2024-07-04T21:05:46.579541Z",
"url": "https://files.pythonhosted.org/packages/1b/28/b8d15278f7dbb5f01aa7f136a109cf92b377def2472e0ae8cb54713ef2da/sphinx_no_pragma-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-04 21:05:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "barseghyanartur",
"github_project": "sphinx-no-pragma",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-no-pragma"
}
JSON
