WIP docs

7 files changed, 188 insertions, 0 deletions

diff --git a/doc/api/index.rst b/doc/api/index.rst
new file mode 100644
index 0000000..b4678f8
--- /dev/null
+++ b/doc/api/index.rst
@@ -0,0 +1,17 @@
+API reference
+=============
+
+.. automodule:: patchtree.config
+   :members:
+
+.. automodule:: patchtree.process
+   :members:
+
+.. automodule:: patchtree.diff
+   :members:
+
+.. automodule:: patchtree.patch
+   :members:
+
+.. automodule:: patchtree.context
+   :members:
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 0000000..07823d6
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,34 @@
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+from os import environ
+from pathlib import Path
+from tomllib import loads as toml_loads
+import sys
+
+repo_root = Path(__file__).parent.parent
+
+sys.path.insert(0, str(repo_root.resolve()))
+import patchtree
+
+project = "patchtree"
+release = "???"
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx_automodapi.automodapi",
+]
+templates_path = []
+exclude_patterns = []
+html_theme = "alabaster"
+html_static_path = []
+autodoc_mock_imports = [project]
+
+try:
+    toml = repo_root.joinpath("pyproject.toml").read_text()
+    pyproject = toml_loads(toml)
+    release = pyproject["project"]["version"]
+except:
+    pass
+
+if "RENESAS_INTERNAL" in environ:
+    extensions.append("lpc_cs_sphinx_renesas_theme")
+    html_theme = "lpc_cs_sphinx_renesas_theme"
diff --git a/doc/dev/diff.rst b/doc/dev/diff.rst
new file mode 100644
index 0000000..6875ed6
--- /dev/null
+++ b/doc/dev/diff.rst
@@ -0,0 +1,5 @@
+Default
+*******
+
+Include
+*******
diff --git a/doc/dev/index.rst b/doc/dev/index.rst
new file mode 100644
index 0000000..6932fa9
--- /dev/null
+++ b/doc/dev/index.rst
@@ -0,0 +1,72 @@
+Developer docs
+==============
+
+Installation
+************
+
+.. note::
+
+   Patchtree is developed and tested on \*NIX-like operating systems.
+   Windows compatibility is not tested or guaranteed.
+   The output .patch files can of course be used anywhere where ``git apply`` works.
+
+Make sure you have the following dependencies installed:
+
+* Python 3 and pip
+* Coccinelle (optional)
+
+Installation can be done by cloning this repository and running
+
+.. code::
+
+   $ pip install .
+
+This will install any missing Python dependencies automatically as well.
+
+Generating clean patches
+************************
+
+In order to generate a clean .patch file, patchtree needs
+
+* the original source tree (either as a folder or .zip file)
+* a list of patch files placed in the same structure as the original source tree
+
+Writing patch sources
+*********************
+
+
+
+.. _config:
+
+Configuration
+*************
+
+.. currentmodule:: patchtree.config
+
+The configuration file is a Python file sourced from ``ptconfig.py`` relative to the current working directory when executing the ``patchtree`` command.
+This file can contain arbitrary Python code.
+Certain global variables influence the behavior of patchtree when defined.
+These variables are the member variables of the :class:`Config` class.
+
+Processors
+**********
+
+.. currentmodule:: patchtree.process
+
+The processors included with patchtree are listed below.
+Custom processors can be created by inheriting from the base :py:class:`Process` class and registering through the `configuration file <config_>`_.
+
+.. toctree::
+   :maxdepth: 1
+
+   processor.rst
+
+Diff engines
+************
+
+The diff engines included with patchtree are listed below.
+
+.. toctree::
+   :maxdepth: 1
+
+   diff.rst
diff --git a/doc/dev/processor.rst b/doc/dev/processor.rst
new file mode 100644
index 0000000..f577220
--- /dev/null
+++ b/doc/dev/processor.rst
@@ -0,0 +1,11 @@
+Touch
+*****
+
+Coccinelle
+**********
+
+Jinja template
+**************
+
+Executable
+**********
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 0000000..8390160
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,11 @@
+.. include:: ../readme.rst
+
+Usage
+*****
+
+.. toctree::
+   :maxdepth: 2
+
+   user/index.rst
+   dev/index.rst
+   api/index.rst
diff --git a/doc/user/index.rst b/doc/user/index.rst
new file mode 100644
index 0000000..2d311c6
--- /dev/null
+++ b/doc/user/index.rst
@@ -0,0 +1,38 @@
+User docs
+=========
+
+.. note::
+
+   By convention, the patch file should be placed in the root of the target directory under the filename ``.patchtree.diff``.
+   This allows you to easily revert and/or upgrade the patch later.
+
+.. important::
+
+   If you keep the target directory under version control, make sure the repository root is the same as the root of the patch's target directory.
+   Patches produced by patchtree contain *extended header lines* which are be interpreted by ``git apply``.
+   Because these header lines must include the path to each modified file relative to the repository root, any files which don't exist at the expected location will be skipped silently by ``git``.
+
+Applying a patch
+****************
+
+To apply patches output by patchtree, download the ``.patch`` file and place it in the directory where it should apply the changes under the name ``.patchtree.diff``.
+
+To apply the patch, run the following command in the target directory::
+
+  $ git apply .patchtree.diff
+
+Reverting a patch
+*****************
+
+To revert the changes of a patch, run the following command in the target directory::
+
+  $ git apply --reverse .patchtree.diff
+
+Upgrading a patch
+*****************
+
+Upgrading a patch consists of
+
+#. reverting the current (old) patch
+#. downloading and replacing the ``.patchtree.diff`` file with the new patch
+#. reapplying the patch file