docs: initialized documentation

CONTRIBUTING.md

@@ -64,7 +64,7 @@ pytest
 We use [sphinx][sphinx] and [autodoc][autodoc] for generating documentation and API references. Besides, we treat warnings as errors while building the documentation. Please fix them before your commits got merged.
 
 ```shell
-cd docs && make html
+cd docs/en && make html
 ```
 
 For documentation preview, you may use any browser you prefer. The executable has to be searchable in `PATH`. For example we're using firefox here.

docs/_apidoc_templates/module.rst_t

@@ -0,0 +1,8 @@
+{%- if show_headings %}
+{{- [basename, "module"] | join(' ') | e | heading }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}

docs/_apidoc_templates/package.rst_t

@@ -0,0 +1,49 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+   :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{%- if is_namespace %}
+{{- [pkgname, "namespace"] | join(" ") | e | heading }}
+{% else %}
+{{- [pkgname, "package"] | join(" ") | e | heading }}
+{% endif %}
+
+{%- if is_namespace %}
+.. py:module:: {{ pkgname }}
+{% endif %}
+
+{%- if modulefirst and not is_namespace %}
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+{%- if subpackages %}
+{{ toctree(subpackages) }}
+{% endif %}
+
+{%- if submodules %}
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{% else %}
+{%- for submodule in submodules %}
+{% if show_headings %}
+{{- [submodule, "module"] | join(" ") | e | heading(2) }}
+{% endif %}
+{{ automodule(submodule, automodule_options) }}
+{% endfor %}
+{%- endif %}
+{%- endif %}
+
+{%- if not modulefirst and not is_namespace %}
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}

docs/_apidoc_templates/toc.rst_t

@@ -0,0 +1,7 @@
+{{ header | heading }}
+
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}

docs/_static/theme_overrides.css

@@ -0,0 +1,55 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+    .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+    }
+
+    .wy-table-responsive {
+      overflow: visible !important;
+    }
+  }
+
+  .wy-side-nav-search {
+    background-color: #e3e3e3 !important;
+  }
+
+  .wy-side-nav-search input[type=text] {
+     border-radius: 0px !important;
+     border-color: #333333 !important;
+  }
+
+  .icon-home {
+    color: #333333 !important;
+  }
+
+  .icon-home:hover {
+    background-color: #d6d6d6 !important;
+  }
+
+  .version {
+    color: #000000 !important;
+  }
+
+  a:hover {
+    color: #bd2c2a !important;
+  }
+
+  .logo {
+    width: 240px !important;
+  }
+
+  .highlight .c1 {
+      color: #008080;
+  }
+
+  .bolditalics {
+      font-weight: bold;
+      font-style: italic;
+  }
+
+pre {
+    white-space: pre-wrap !important;
+}

docs/_templates/layout.html

@@ -0,0 +1,7 @@
+{% extends "!layout.html" %}
+
+{% block document %}
+<!--email_off-->
+    {{ super() }}
+<!--/email_off-->
+{% endblock %}

docs/conf_common.py

@@ -0,0 +1,53 @@
+# SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0
+
+
+# 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
+from datetime import datetime
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'esp-bool-parser'
+project_homepage = 'https://github.com/espressif/esp-bool-parser'
+copyright = f'2024-{datetime.now().year}, Espressif Systems (Shanghai) Co., Ltd.'  # noqa: A001
+author = 'Fu Hanxi'
+languages = ['en']
+version = '0.x'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx_copybutton',
+    'myst_parser',
+    'sphinxcontrib.mermaid',
+    'sphinxarg.ext',
+    'sphinx_tabs.tabs',
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_css_files = ['theme_overrides.css']
+html_logo = '../_static/espressif-logo.svg'
+html_static_path = ['../_static']
+html_theme = 'sphinx_rtd_theme'
+
+# mermaid 10.2.0 will show syntax error
+# use fixed version instead
+mermaid_version = '10.6.1'
+
+autodoc_default_options = {
+    'members': True,
+    'member-order': 'bysource',
+    'show-inheritance': True,
+    'exclude-members': 'model_computed_fields,model_config,model_fields,model_post_init',
+}

docs/en/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    ?= -W
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+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/en/conf.py

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: Apache-2.0
+
+import os
+import sys
+
+language = 'en'
+
+sys.path.insert(0, os.path.abspath('../'))
+
+from conf_common import *  # noqa

docs/en/index.rst

@@ -0,0 +1,48 @@
+#########################################
+ esp-bool-parser |version| Documentation
+#########################################
+
+This documentation is for esp-bool-parser. esp-bool-parser is a package which help process boolean statements based on `soc_caps` files in the ESP-IDF.
+
+*****************
+ esp-bool-parser
+*****************
+
+`esp-bool-parser` is a package that provides a way to process boolean statements based on `soc_caps` files in the ESP-IDF.
+
+It helps you locate `soc_headers` files in the ESP-IDF, parse them, and store the parsed values as constants, which are then used in `ChipAttr`.
+
+When you import `esp_bool_parser`, you will gain access to **`BOOL_EXPR`**, a parser for boolean expressions.
+
+***************
+ Usage Example
+***************
+
+.. code:: python
+
+   stmt_string = 'IDF_TARGET == "esp32"'
+   stmt: BoolStmt = BOOL_EXPR.parseString(stmt_string)[0]
+   stmt.get_value("esp32", "config_name")
+
+***************
+ Extendability
+***************
+
+You can extend the functionality of `ChipAttr` by adding custom handlers for new attributes. Use the `register_addition_attribute` function to register additional attributes. When these attributes are encountered, the associated handler function will be called. Additionally, you can override existing attributes, as the newly registered handler will take priority over the original ones.
+
+Example:
+
+.. code:: python
+
+   def custom_handler(target: str, config_name: str) -> Any:
+       # Custom logic to handle the attribute
+       return "custom_value"
+
+   register_addition_attribute("CUSTOM_ATTR", custom_handler)
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Others
+   :glob:
+
+   others/*

docs/en/others/CHANGELOG.md

@@ -0,0 +1,2 @@
+```{include} ../../../CHANGELOG.md
+```

docs/en/others/CONTRIBUTING.md

@@ -0,0 +1,2 @@
+```{include} ../../../CONTRIBUTING.md
+```