Overview#

Prerequisites#

  • python >= 3.8 (this package was developed on 3.8 and tested on minor versions from 3.8 to 3.12).

Installation#

pip install ndf-parse

Note

Note that if you didn’t add python to the PATH variable during installation, you’ll have to run it with full path to pip, for example "C:\Users\User\AppData\Local\Python311-64\Scripts\pip.exe" install ndf_parse

As an alternative, you can download and install this package from github releases.

Using This Package#

For usage please refer to the documentation.

Caveats#

This package gets shipped with an ndf.dll containing the tree-sitter language parser. It’s linkage is also hardcoded in module’s __init__. If you’re planning to use this on linux or MacOS (why?..), you will have to build the lib yourself and set an env variable NDF_LIB_PATH=path/to/your/lib.

Developing#

In order to develop this module you will need to fork this repo, clone the fork and run the following command:

pip install -e "path\to\cloned\repo[dev]"

It will load most dependencies automatically. Only thing you will have to provide manually is an ndf.dll (see below). You can then build a release package using scripts\build_package.bat script. It outputs the result to a build\package folder. By default the build sctipt uses a local library (ndf_parse\bin\ndf.dll). If there is none, it copies one from tree-sitter’s default build path to local path. If there is also none then it refuses to build.

black is used for code styling with line length limit == 79. Code is (mostly) type hinted.

.gitignore does not store editor specific excludes, I store those in .git\info\exclude.

Repo Structure#

  • build - temp folder to store build data, untracked

  • ndf_parse - package source code

  • sphinx - documentation sources

  • scripts - mostly scripts for building stuff

  • tests - basic testing scripts

Docs Development#

Current Version Build#

To build docs for current commit use scripts\build_docs.bat. Your docs will be in build\docs.

Multiversion Build#

To build docs for all releases follow these steps:

  1. Make sure to bump release version and commit all changes related to the latest release (and stash what is left).

  2. Tag the release with semver (example: v1.0.5, v is mandatory).

  3. Add new tag to publish_tags variable in sphinx\conf.py.

  4. Remove build\multiver to ensure clean build.

  5. Run python scripts\build_multidocs.py. Result will be in build\multiver.

  6. Checkout docs branch.

  7. Remove old docs dirs (named by their releases), move new ones, including build\multiver\index.html (but excluding .doctree dirs in each version build, they are not needed for serving), to the root of the repo.

  8. Add new stuff to git (be careful not to include junk, there is no .gitignore) and commit.

Note

Things to keep in mind: sphinx-multiversion arranges releases based on commit date, not semver number. So be careful when rebasing/amending older releases.

Tests#

If you’re planning to test scripts from the documentation (the ones in sphinx\code), you will have to setup 2 env variables in your terminal:

set MOD_SRC="path\to\source_mod"
set MOD_DST="path\to\destination_mod"

Currently there are only tests for ndf_parse.model and docs’ code snippets and examples. Docstrings code is tested with sphinx via tests\docs_tests.bat, py script with the same name has examples tests and a deprecated version of doctests.

Using in Pair With Custom tree-sitter-ndf#

This package looks for an ntf.dll in the following places (descending priority):

  1. NDF_LIB_PATH env variable ("C:\custom\path\to\ndf.dll"),

  2. default tree-sitter’s build path ("%LocalAppData%\tree-sitter\lib\ndf.dll"),

  3. a copy bundled with the package ("ndf_parse\bin\ndf.dll").

The repo itself does not hold a prebuilt copy of the library so you’ll have to either yank one from a release wheel (it’s just a renamed zip) or build one from source.

Pull Requests and Issues#

I have no idea on how frequently I’ll be able to respond to those, so expect delays. You might find it easier catching me on WarYes discord or Eugen discord in case you have some blocking issue or a PR.

Credits#

Created by Ulibos, 2023-2024.