Metadata-Version: 2.4
Name: ndx
Version: 0.5.0
Summary: Build annotated index file for a directory.
Author: M. Farzalipour Tabriz
License-Expression: GPL-3.0-or-later
License-File: LICENSES/GPL-3.0-or-later.txt
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Dist: google-re2>=1.1.20251105
Requires-Dist: jsonschema>=4.26.0
Requires-Dist: nh3>=0.3.7
Requires-Python: >=3.10
Project-URL: source, https://gitlab.mpcdf.mpg.de/tbz/ndx.git
Description-Content-Type: text/x-rst

***
ndx
***
A static HTML directory index generator.

``ndx`` is a command-line utility for generating index files for directories. It supports file annotations via a JSON configuration file.

Installation
############
.. code-block:: shell

    pipx install ndx

Usage
#####
To generate an index in a specific directory, use:

.. code-block:: shell

    ndx /path/to/directory

Generate index files recursively:

.. code-block:: shell

    ndx --recursive /path/to/directory

Options
*******
.. code-block:: shell

    usage: ndx [-h] [-r] [--max-depth MAX_DEPTH] [-f] [-v] [--version] directory

    Build an annotated index file for a directory.

    positional arguments:
    directory             path to the target directory

    options:
    -h, --help            show this help message and exit
    -r, --recursive       build index files recursively (default: False)
    --max-depth MAX_DEPTH
                            maximum recursion depth for building index files (default: 50)
    -f, --force           overwrite existing index.html file(s) (default: False)
    -v, --verbose         enable verbose logging (default: False)
    --version             show program's version number and exit

Configuration
#############

To customize the index by adding descriptions to the page and files, place a ``.ndx.json`` file in the target directory.

Schema
******

.. code-block:: json

    {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
            "page": {
                "type": "object",
                "properties": {"description": {"type": "string", "maxLength": 10000}},
                "required": ["description"],
                "additionalProperties": false,
            },
            "files": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "name_regex": {
                            "type": "string",
                            "maxLength": 200,
                            "format": "re2-pattern",
                        },
                        "description": {"type": "string", "maxLength": 1000},
                    },
                    "required": ["name_regex", "description"],
                    "additionalProperties": false,
                },
            },
        },
        "additionalProperties": false,
    }

Example
*******

.. code-block:: json

    {
      "page": {
        "description": "For more information, please refer to the <a href='https://docs.example.com'>documentation</a> website."
      },
      "files": [
        {
          "name_regex": ".*\\.pdf$",
          "description": "Full documentation"
        },
        {
          "name_regex": ".*\\.log$",
          "description": "Build logs"
        }
      ]
    }

Design Choices and Limitations
##############################
- Data integrity is only guaranteed on POSIX-compliant systems.
- Only `RE2 regexes <https://github.com/google/re2/wiki/Syntax>`_ are supported.
- Descriptions only support HTML anchor tags (``<a href=''>...</a>``).
- Only HTTPS links are supported in the descriptions.
- All attributes except the link target are stripped from the HTML anchor tags and ``target="_blank"`` is added to them.
- Hidden files (starting with ``.``) and the index file ``index.html`` are skipped.
- A warning is issued and notes are skipped for files that match multiple regexes.
- Support for hardlinks on the target directory is required unless the ``--force`` option is used.

History
#######
This script was originally developed for the `linkmedic <https://pypi.org/project/linkmedic/>`_ project.

License
#######
* Copyright 2025-2026 M. Farzalipour Tabriz, Max Planck Institute for Physics (MPP)

All rights reserved.

This software may be modified and distributed under the terms of the GPL-3.0 (or later) License. See the ``LICENSE`` file for details.
