docs: initiate WML documentation with Sphinx

Started the process of creating comprehensive documentation for the World Modeling Language (WML) using Sphinx. This includes setting up the Sphinx project, configuring it for HTML output, and drafting initial content.

- Set up a Sphinx project.
- Integrated WML source files.
- Configured Sphinx to generate HTML documentation.
- Drafted initial section: Introduction. Installation guide, Syntax and semantics, Examples and use cases, API reference will be pushed in the following commits.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/bytecode.rst

@@ -0,0 +1,7 @@
+bytecode module
+===============
+
+.. automodule:: bytecode
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/conf.py

@@ -0,0 +1,45 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+#
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import os
+import sys
+from datetime import date
+from pathlib import Path
+
+src = Path(__file__).parent.parent / 'src'
+sys.path.insert(0, str(src))
+
+current_year = date.today().year
+
+project = 'WML'
+author = 'Kenny Lajara'
+copyright = f'{current_year}, {author}'
+release = '0.1.0-alpha'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'myst_parser',
+    'sphinx.ext.autodoc',
+]
+source_suffix = ['.rst', '.md']
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+html_css_files = [
+    'css/style.css',
+]
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'furo'
+html_static_path = ['_static']

docs/source/index.md

@@ -0,0 +1,42 @@
+# WML - World Modeling Language
+
+**World Modeling Language (WML)** is a programming language designed for modeling real-world systems with ease.
+It's meant to facilitate AI research and introduce deterministic instructions into AI model.
+
+This is the official documentation for WML. It is a work in progress and will be updated regularly.
+
+```{warning}
+WML is in **Alpha stage**, things may change rapidly. It is not recommended for production use.
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Ensure you have Python installed. WML is developed and tested with Python 3.11. Other versions may work, but are not
+officially supported (yet).
+
+### Installation
+
+1. Clone the repository:
+```{code-block} bash
+---
+linenos: true
+emphasize-lines: 1, 2
+---
+git clone https://github.com/kennylajara/WML.git
+cd WML
+```
+
+2. Install the required dependencies:
+```{code-block} bash
+---
+linenos: true
+emphasize-lines: 1
+---
+pip install -r requirements.txt
+```
+
+```{eval-rst}
+.. autofunction:: wml.sphinx_example
+```

docs/source/main.rst

@@ -0,0 +1,7 @@
+main module
+===========
+
+.. automodule:: main
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/modules.rst

@@ -0,0 +1,10 @@
+src
+===
+
+.. toctree::
+   :maxdepth: 4
+
+   bytecode
+   main
+   run_script_many_times
+   wml

docs/source/wml.meta.rst

@@ -0,0 +1,21 @@
+wml.meta package
+================
+
+Submodules
+----------
+
+wml.meta.patterns module
+------------------------
+
+.. automodule:: wml.meta.patterns
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: wml.meta
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/wml.rst

@@ -0,0 +1,95 @@
+wml package
+===========
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   wml.meta
+   wml.tests
+   wml.utils
+
+Submodules
+----------
+
+wml.ast module
+--------------
+
+.. automodule:: wml.ast
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+wml.builtings module
+--------------------
+
+.. automodule:: wml.builtings
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+wml.errors module
+-----------------
+
+.. automodule:: wml.errors
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+wml.evaluator module
+--------------------
+
+.. automodule:: wml.evaluator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+wml.lexer module
+----------------
+
+.. automodule:: wml.lexer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+wml.object module
+-----------------
+
+.. automodule:: wml.object
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+wml.parser module
+-----------------
+
+.. automodule:: wml.parser
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+wml.repl module
+---------------
+
+.. automodule:: wml.repl
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+wml.token module
+----------------
+
+.. automodule:: wml.token
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: wml
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/wml.tests.rst

@@ -0,0 +1,45 @@
+wml.tests package
+=================
+
+Submodules
+----------
+
+wml.tests.ast\_test module
+--------------------------
+
+.. automodule:: wml.tests.ast_test
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+wml.tests.evaluator\_test module
+--------------------------------
+
+.. automodule:: wml.tests.evaluator_test
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+wml.tests.lexer\_test module
+----------------------------
+
+.. automodule:: wml.tests.lexer_test
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+wml.tests.parser\_test module
+-----------------------------
+
+.. automodule:: wml.tests.parser_test
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: wml.tests
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/wml.utils.rst

@@ -0,0 +1,21 @@
+wml.utils package
+=================
+
+Submodules
+----------
+
+wml.utils.regex module
+----------------------
+
+.. automodule:: wml.utils.regex
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: wml.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

requirements.txt

@@ -1,2 +1,9 @@
-mypy==1.10.1
-pytest==8.2.2
+# Code quality
+mypy>=1.10.1,<1.11.0  # Static type checker
+pytest>=8.2.2,<8.3.0  # Testing framework
+
+# Docs
+furo==2024.5.6  # Theme
+myst-parser>=3.0.1,<3.1.0  # Markdown parser
+Sphinx>=7.3.7,<8.4.0  # Documentation generator
+#sphinx-autodoc-typehints>=1.12.0,<1.13.0  # Type hints support