Skip to content

Commit c8f6319

Browse files
MichaelGoodaleMichaelGoodale
committed
Initial documentation set-up
1 parent fc6089d commit c8f6319

16 files changed

Lines changed: 1075 additions & 16 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ instance/
7272

7373
# Sphinx documentation
7474
docs/_build/
75+
docs/build/
7576

7677
# PyBuilder
7778
.pybuilder/

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/source/conf.py‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
import sys
2+
import os
3+
4+
# Configuration file for the Sphinx documentation builder.
5+
#
6+
# For the full list of built-in configuration values, see the documentation:
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
8+
9+
# -- Project information -----------------------------------------------------
10+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
11+
12+
project = "Python Minimalist Grammars"
13+
copyright = "2025, Michael Goodale"
14+
author = "Michael Goodale"
15+
release = "0.1"
16+
17+
# -- General configuration ---------------------------------------------------
18+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
19+
sys.path.insert(0, os.path.abspath("../../python/"))
20+
extensions = [
21+
"sphinx.ext.autodoc",
22+
# "sphinx.ext.autosummary",
23+
"sphinx.ext.napoleon",
24+
"sphinx_rtd_theme",
25+
]
26+
27+
templates_path = ["_templates"]
28+
exclude_patterns = []
29+
30+
napoleon_numpy_docstring = True
31+
32+
# autosummary_generate = True
33+
# autosummary_imported_members = True
34+
# -- Options for HTML output -------------------------------------------------
35+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
36+
37+
html_theme = "sphinx_rtd_theme"
38+
html_static_path = ["_static"]

‎docs/source/graphing.rst‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
Graphing utilities
2+
==================
3+
4+
These are the classes that are useful for manipulating or plotting parse trees directly.
5+
6+
.. autoclass:: python_mg.ParseTree
7+
:members:
8+
:undoc-members:
9+
:show-inheritance:
10+
11+
.. autoclass:: python_mg.Mover
12+
:members:
13+
:undoc-members:
14+
:show-inheritance:
15+
16+
.. autoclass:: python_mg.Trace
17+
:members:
18+
:undoc-members:
19+
:show-inheritance:

‎docs/source/index.rst‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
.. Python Minimalist Grammars documentation master file, created by
2+
sphinx-quickstart on Wed Oct 15 11:30:51 2025.
3+
You can adapt this file completely to your liking, but it should at least
4+
contain the root `toctree` directive.
5+
6+
Python Minimalist Grammars documentation
7+
========================================
8+
9+
This documents the `python-mg <github.com/MichaelGoodale/python-mg>`_ package which contains Python bindings for `a Minimalist Grammar parser written in Rust <https://github.com/MichaelGoodale/minimalist-grammar-parser>`_.
10+
It provides the tools necessary to generate strings from a Minimalist Grammar and parse sentences in a Minimalist Grammar, as well as inspecting their parse tree.
11+
12+
.. toctree::
13+
:maxdepth: 2
14+
:caption: Contents:
15+
16+
lexicon
17+
graphing
18+
metrics
19+
20+
21+
Installation
22+
------------
23+
24+
The package is made with `Maturin <https://github.com/PyO3/maturin>`_ and can be build however you'd like using that system.
25+
The easiest way to build it or develop with it is by using `uv <https://github.com/astral-sh/uv>`_.
26+
27+
.. code-block:: bash
28+
29+
git clone https://github.com/MichaelGoodale/python-mg
30+
cd python-mg
31+
uv run example.py
32+
33+
Otherwise, you can also install it with `pip` or other tools as a wheel by getting it from `the GitHub actions page <https://github.com/MichaelGoodale/python-mg/actions>`_
34+
35+
You can also add it to a uv project like so:
36+
37+
.. code-block:: bash
38+
39+
uv add git+https://github.com/MichaelGoodale/python-mg
40+
41+
42+
43+
Usage
44+
-----
45+
46+
The following snippet declares a grammar, parses a sentence and generates a string in the grammar.
47+
48+
.. code-block:: python
49+
50+
from python_mg import Lexicon
51+
52+
grammar = """
53+
::V= C
54+
::V= +W C
55+
knows::C= =D V
56+
says::C= =D V
57+
prefers::D= =D V
58+
drinks::D= =D V
59+
king::N
60+
wine::N
61+
beer::N
62+
queen::N
63+
the::N= D
64+
which::N= D -W
65+
"""
66+
lexicon = Lexicon(grammar)
67+
68+
for p in lexicon.parse("which beer the queen drinks", "C"):
69+
tree = p.to_tree()
70+
tree.to_image().show()
71+
72+
for p in lexicon.generate_grammar("C", max_strings=1):
73+
print(p)
74+
print(p.latex())
75+
print(p.to_tree().to_dot())
76+
p.to_tree().to_image().show()
77+
78+
The parse tree can also be turned into LaTeX code with Forest (see `latex-commands.tex <https://github.com/MichaelGoodale/python-mg/blob/master/latex-commands.tex>`_) or can be directly turned into a GraphViz Dot file.

‎docs/source/lexicon.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
Core classes
2+
============
3+
4+
These are the core classes and functions which make up the library.
5+
6+
.. autoclass:: python_mg.Lexicon
7+
:members:
8+
:undoc-members:
9+
:show-inheritance:
10+
11+
12+
.. autoclass:: python_mg.SyntacticStructure
13+
:members:
14+
:undoc-members:
15+
:show-inheritance:
16+
17+
.. autoclass:: python_mg.Continuation
18+
:members:
19+
:undoc-members:
20+
:show-inheritance:

‎docs/source/metrics.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
Metrics
2+
=======
3+
4+
This outlines metrics that make it easy to calculate the grammar F1 of an autoregressive model trained on a Minimalist Grammar.
5+
6+
.. automodule:: python_mg.metrics
7+
:members:
8+
:undoc-members:
9+
:show-inheritance:

‎examples/generate_strings.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,3 +35,4 @@
3535

3636
# A rich string which illustrates where movement was generated from
3737
print(tree.base_string())
38+
print(tree.to_dot())

‎pyproject.toml‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,12 @@ python-source = "python"
2323
module-name = "python_mg._lib_name"
2424

2525
[dependency-groups]
26-
dev = ["patchelf>=0.17.2.2", "pytest>=8.3.5"]
26+
dev = [
27+
"patchelf>=0.17.2.2",
28+
"pytest>=8.3.5",
29+
"sphinx>=7.1.2",
30+
"sphinx-rtd-theme>=3.0.2",
31+
]
2732
examples = [
2833
"datasets>=3.1.0",
2934
"scipy>=1.10.1",

0 commit comments

Comments
 (0)