Merge pull request #52 from barseghyanartur/dev

Update docs (#51)

.pre-commit-config.yaml

@@ -20,7 +20,7 @@ repos:
         args: []
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.6.0
     hooks:
       - id: trailing-whitespace
         exclude: "data/"
@@ -33,23 +33,23 @@ repos:
       - id: check-merge-conflict
 
   - repo: https://github.com/psf/black
-    rev: 23.1.0
+    rev: 24.4.2
     hooks:
       - id: black
         name: black
         files: .
         args: [ "--config", "pyproject.toml" ]
 
   - repo: https://github.com/pycqa/isort
-    rev: 5.12.0
+    rev: 5.13.2
     hooks:
       - id: isort
         name: isort
         files: .
         args: [ "--settings-path", "pyproject.toml", "--profile=black" ]
 
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.0.252
+    rev: v0.4.4
     hooks:
       - id: ruff
         name: lint

.secrets.baseline

@@ -1,5 +1,5 @@
 {
-  "version": "1.4.0",
+  "version": "1.5.0",
   "plugins_used": [
     {
       "name": "ArtifactoryDetector"
@@ -118,14 +118,14 @@
         "filename": "Makefile",
         "hashed_secret": "ee783f2421477b5483c23f47eca1f69a1f2bf4fb",
         "is_verified": true,
-        "line_number": 40
+        "line_number": 43
       },
       {
         "type": "Secret Keyword",
         "filename": "Makefile",
         "hashed_secret": "1457a35245051927fac6fa556074300f4162ed66",
         "is_verified": true,
-        "line_number": 43
+        "line_number": 46
       }
     ]
   },

Makefile

@@ -10,6 +10,9 @@ build_docs:
 	source $(VENV) && sphinx-build -n -a -b html docs builddocs
 	cd builddocs && zip -r ../builddocs.zip . -x ".*" && cd ..
 
+pre-commit:
+	pre-commit run --all-files
+
 # Format code using Black
 black:
 	source $(VENV) && black .
@@ -25,9 +28,9 @@ doc8:
 ruff:
 	source $(VENV) && ruff .
 
-# Serve the built docs on port 5000
+# Serve the built docs on port 5001
 serve_docs:
-	source $(VENV) && cd builddocs && python -m http.server 5000
+	source $(VENV) && cd builddocs && python -m http.server 5001
 
 # Install the project
 install:
@@ -62,7 +65,10 @@ clean:
 	rm -rf dist/
 
 compile-requirements:
-	source $(VENV) && python -m piptools compile --extra all -o docs/requirements.txt pyproject.toml
+	source $(VENV) && python -m piptools compile --all-extras -o docs/requirements.txt pyproject.toml
+
+compile-requirements-upgrade:
+	source $(VENV) && python -m piptools compile --all-extras -o docs/requirements.txt pyproject.toml --upgrade
 
 TAGS = sphinx_rtd_theme alabaster sphinx_material bootstrap furo sphinx_book_theme pydata_sphinx_theme
 

README.rst

@@ -103,8 +103,38 @@ Impressed? Want to know how it works?
 
 Under the hood
 ==============
-``jsphinx-download`` directive
-------------------------------
+For total clarity, see the following tree structure of the ``docs`` directory,
+located in the project root (a typical location for storing project docs):
+
+.. code-block:: sh
+
+    ├── conf.py
+    ├── examples -> ../examples
+    │   └── simple
+    │       ├── snippet_1.py
+    │       ├── snippet_2.py
+    │       ├── snippet_3.py
+    │       └── snippet_4.py
+    ├── example.rst
+    ├── index.rst
+    └── test_docs.py
+
+
+- The ``conf.py`` is the `Sphinx`_ configuration file.
+- The ``examples`` directory, in this case, is sym-linked to an ``examples``
+  directory located in the project root.
+- The ``snippet_*.py`` files are simple standalone Python code
+  examples/snippets.
+- The ``example.rst`` file is a part of the supposed documentation, containing
+  source code examples.
+- The ``index.rst`` is the entry-point of the supposed documentation.
+- The ``test_docs.py`` is a Python module containing tests (of all code
+  examples/snippets).
+
+----
+
+``.. container:: jsphinx-download`` directive
+---------------------------------------------
 `Sphinx`_ is a documentation generator. It has many directives, among which
 the ``.. literalinclude::``, which allows us to include content of a file
 directly into your documentation.
@@ -114,8 +144,9 @@ specify which parts of the code to show. That's what we use to keep the
 primary focus on the most important parts of the code, reducing cognitive
 load for the reader.
 
-Consider the following code example stored in a
-file ``_static/py/faker_file_docx_1.py``:
+Consider the following code example:
+
+*Filename: examples/simple/snippet_1.py*
 
 .. code-block:: python
 
@@ -136,11 +167,13 @@ file ``_static/py/faker_file_docx_1.py``:
    print(docx_file.data["filename"])
    assert os.path.exists(docx_file.data["filename"])
 
-See the following snippet:
+See the following documentation snippet:
+
+*Filename: example.rst*
 
 .. code-block:: rst
 
-    .. literalinclude:: _static/py/faker_file_docx_1.py
+    .. literalinclude:: examples/simple/snippet_1.py
        :language: python
        :lines: 3-11
 
@@ -164,22 +197,24 @@ link to a file (the same file we already included into the documentation
 using ``.. literalinclude::``). By that we ensure that those interested in the
 complete code can easily access it.
 
-See the following snippet:
+See the following documentation snippet:
+
+*Filename: example.rst*
 
 .. code-block:: rst
 
     .. container:: jsphinx-download
 
         *See the full example*
-        :download:`here <_static/py/faker_file_docx_1.py>`
+        :download:`here <examples/simple/snippet_1.py>`
 
 The above mentioned snippet will be produce the following HTML:
 
 .. code-block:: html
 
    <p class="jsphinx-download">
      <em>See the full example</em>
-     <a class="reference download internal" href="_static/py/faker_file_docx_1.py">
+     <a class="reference download internal" href="examples/simple/snippet_1.py">
        <span class="pre">here</span>
      </a>
    </p>
@@ -188,19 +223,20 @@ The above mentioned snippet will be produce the following HTML:
 
 This is where ``jsphinx`` steps in. Using provided JavaScript,
 we hook to the links generated by the ``:download:`` directive and instead
-of downloading the content, show it in-line, right in place.
+of downloading the content, show it inline, right in place.
 
-Note, that although ``.. container:: jsphinx-download`` technically
-isn't strictly required, it wraps our link into an element with
-``jsphinx-download`` class so that we can safely hook to all underlying
-download links without a risk to cause unwanted behavior for other places
-where you might have used ``:download:`` directive for other purposes.
+The ``.. container:: jsphinx-download`` directive wraps our link into an
+element with ``jsphinx-download`` class so that we can safely hook to all
+underlying download links without a risk to cause unwanted behavior for other
+places where you might have used ``:download:`` directive for other purposes.
 
 Finally, `PrismJS`_ syntax highlighter is used to beautify the code and make
 it look close to the code highlighting of your `Sphinx`_ theme of choice.
 
-``jsphinx-toggle-emphasis`` directive
--------------------------------------
+----
+
+``.. container:: jsphinx-toggle-emphasis`` directive
+----------------------------------------------------
 Another popular `Sphinx`_ directive is the ``.. code-block::``, which enables
 us to display code blocks within your documentation.
 
@@ -209,7 +245,9 @@ which is particularly useful for highlighting specific lines of code within
 the code block. This helps to draw attention to most important  parts of the
 code and helps the reader to understand the code.
 
-Consider the following example:
+Consider the following documentation snippet:
+
+*Filename: example.rst*
 
 .. code-block:: rst
 
@@ -273,6 +311,8 @@ Configuration
 To integrate both into your `Sphinx`_ project, add the following in
 your ``conf.py``:
 
+*Filename: conf.py*
+
 .. code-block:: python
 
    # ************************************************************
@@ -298,6 +338,8 @@ your ``conf.py``:
 A complete configuration example, together with loaded `PrismJS`_ and the
 toolbar with plugins, would look as follows:
 
+*Filename: conf.py*
+
 .. code-block:: python
 
    prismjs_base = "//cdnjs.cloudflare.com/ajax/libs/prism/1.29.0"
@@ -325,6 +367,8 @@ You can also use other `Sphinx`_ themes, such as `alabaster`_, `furo`_,
 Make sure to specify appropriate value (theme key) in ``html_theme``,
 as follows (pick one):
 
+*Filename: conf.py*
+
 .. code-block:: python
 
    html_theme = "alabaster"
@@ -337,6 +381,8 @@ as follows (pick one):
 
 Finally, make sure to specify correct path to the desired theme:
 
+*Filename: conf.py*
+
 .. code-block:: python
 
    html_css_files = [
@@ -353,19 +399,20 @@ All code snippets of this repository can be tested with `pytest`_ as follows:
 
     pytest
 
-The `pytest`_ test-runner finds tests in the ``docs/test_docs.py`` module,
+The `pytest`_ test-runner finds tests in the ``test_docs.py`` module,
 which is responsible for dynamical execution of Python files located in the
-``docs/_static/py/`` directory.
+``examples/simple/`` directory (``docs/examples/simple`` from the project
+root). This is how ``test_docs.py`` could look:
 
-This is how ``docs/test_docs.py`` could look:
+*Filename: test_docs.py*
 
 .. code-block:: python
 
     from pathlib import Path
     import pytest
 
     # Walk through the directory and all subdirectories for .py files
-    example_dir = Path("docs/_static/py")
+    example_dir = Path("docs/examples/simple")
     py_files = sorted([str(p) for p in example_dir.rglob("*.py")])
 
     def execute_file(file_path):

docs/conf.py

@@ -24,6 +24,7 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
+    "sphinx_no_pragma",
 ]
 pygments_style = "sphinx"
 templates_path = ["_templates"]

docs/examples

@@ -0,0 +1 @@
+../examples