#66: Improve docs

docs/requirements.txt

@@ -2,8 +2,9 @@ sphinx >= 4.1, < 5
 sphinx-material
 sphinx-tabs
 sphinx-jinja==1.1.1
+docker
 
 -e src/process/ --pre
 -e src/pythonic/ --pre
-# -e src/php/ --pre
+-e src/php/ --pre
 -e src/core/ --pre

docs/source/conf.py

@@ -1,3 +1,4 @@
+import os
 from distutils.version import LooseVersion
 import sphinx_material
 
@@ -23,9 +24,115 @@
     "sphinx.ext.todo",
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
-    "sphinx_tabs.tabs"
+    "sphinx_tabs.tabs",
+    "sphinxcontrib.jinja"
 ]
 
+jinja_contexts = {
+    'py_publish': {
+        'PKG_NAME': 'rkd_python',
+        'PKG_CLASS_NAME': 'rkd_python.PublishTask',
+        'PKG_PIP': 'rkd_python'
+    },
+    'py_build': {
+        'PKG_NAME': 'rkd_python',
+        'PKG_CLASS_NAME': 'rkd_python.BuildTask',
+        'PKG_PIP': 'rkd_python'
+    },
+    'py_install': {
+        'PKG_NAME': 'rkd_python',
+        'PKG_CLASS_NAME': 'rkd_python.InstallTask',
+        'PKG_PIP': 'rkd_python'
+    },
+    'py_clean': {
+        'PKG_NAME': 'rkd_python',
+        'PKG_CLASS_NAME': 'rkd_python.CleanTask',
+        'PKG_PIP': 'rkd_python'
+    },
+    'py_unittest': {
+        'PKG_NAME': 'rkd_python',
+        'PKG_CLASS_NAME': 'rkd_python.UnitTestTask',
+        'PKG_PIP': 'rkd_python'
+    },
+    'shell': {
+        'PKG_NAME': 'rkd.core.standardlib.shell',
+        'PKG_CLASS_NAME': 'rkd.core.standardlib.shell.ShellCommandTask',
+        'PKG_PIP': 'rkd'
+    },
+    'exec': {
+        'PKG_NAME': 'rkd.core.standardlib.shell',
+        'PKG_CLASS_NAME': 'rkd.core.standardlib.shell.ExecProcessCommand',
+        'PKG_PIP': 'rkd'
+    },
+    'j2_render': {
+        'PKG_NAME': 'rkd.core.standardlib.jinja',
+        'PKG_CLASS_NAME': 'rkd.core.standardlib.jinja.FileRendererTask',
+        'PKG_PIP': 'rkd'
+    },
+    'j2_directory_to_directory': {
+        'PKG_NAME': 'rkd.core.standardlib.jinja',
+        'PKG_CLASS_NAME': 'rkd.core.standardlib.jinja.RenderDirectoryTask',
+        'PKG_PIP': 'rkd'
+    },
+    'init': {
+        'PKG_NAME': 'rkd.core.standardlib',
+        'PKG_CLASS_NAME': 'rkd.core.standardlib.InitTask',
+        'PKG_PIP': 'rkd'
+    },
+    'tasks': {
+        'PKG_NAME': 'rkd.core.standardlib',
+        'PKG_CLASS_NAME': 'rkd.core.standardlib.TasksListingTask',
+        'PKG_PIP': 'rkd'
+    },
+    'callable_task': {
+        'PKG_NAME': 'rkd.core.standardlib',
+        'PKG_CLASS_NAME': 'rkd.core.standardlib.CallableTask',
+        'PKG_PIP': 'rkd'
+    },
+    'rkd_create_structure': {
+        'PKG_NAME': 'rkd.core.standardlib',
+        'PKG_CLASS_NAME': 'rkd.core.standardlib.CreateStructureTask',
+        'PKG_PIP': 'rkd'
+    },
+    'version': {
+        'PKG_NAME': 'rkd.core.standardlib',
+        'PKG_CLASS_NAME': 'rkd.core.standardlib.VersionTask',
+        'PKG_PIP': 'rkd'
+    },
+    'env_get': {
+        'PKG_NAME': 'rkd.core.standardlib.env',
+        'PKG_CLASS_NAME': 'rkd.core.standardlib.env.SetEnvTask',
+        'PKG_PIP': 'rkd'
+    },
+    'env_set': {
+        'PKG_NAME': 'rkd.core.standardlib.env',
+        'PKG_CLASS_NAME': 'rkd.core.standardlib.env.GetEnvTask',
+        'PKG_PIP': 'rkd'
+    },
+    'line_in_file': {
+        'PKG_NAME': 'rkd.core.standardlib',
+        'PKG_CLASS_NAME': 'rkd.core.standardlib.LineInFileTask',
+        'PKG_PIP': 'rkd'
+    },
+    'ArchivePackagingBaseTask': {
+        'PKG_NAME': 'rkd.core.standardlib.io',
+        'PKG_CLASS_NAME': 'rkd.core.standardlib.io.ArchivePackagingBaseTask',
+        'PKG_PIP': 'rkd'
+    },
+    'PhpScriptTask': {
+        'PKG_NAME': 'rkd.php.script',
+        'PKG_CLASS_NAME': 'rkd.php.script.PhpScriptTask',
+        'PKG_PIP': 'rkd.php'
+    },
+    'RunInContainerBaseTask': {
+        'PKG_NAME': 'rkd.core.standardlib.docker',
+        'PKG_CLASS_NAME': 'rkd.core.standardlib.docker.RunInContainerBaseTask',
+        'PKG_PIP': 'rkd'
+    }
+}
+
+jinja_base = os.path.realpath(os.path.dirname(os.path.realpath(__file__)) + '/../')
+
 autosummary_generate = True
 autoclass_content = "class"
 

docs/source/extending-tasks.rst

@@ -1,3 +1,4 @@
+.. _Extending tasks:
 Extending tasks
 ===============
 

docs/source/standardlib/docker.rst

@@ -0,0 +1,22 @@
+Docker
+======
+
+RunInContainerBaseTask
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+- inner_execute() should be used to execute a code while the container is running
+- execute() should not be overridden
+
+.. jinja:: RunInContainerBaseTask
+   :file: source/templates/package-usage.rst
+
+.. CAUTION::
+    This is a Base Task. It is not a Task to run, but to create a **own, runnable Task** basing on it.
+
+.. HINT::
+    This is an extendable task. Read more in :ref:`Extending tasks` chapter.
+
+
+.. autoclass:: rkd.core.standardlib.docker.RunInContainerBaseTask
+   :exclude-members: get_name, get_group_name
+   :members:

docs/source/standardlib/index.rst

@@ -10,5 +10,8 @@ Built-in tasks
    shell
    technical
    python
+   php
    env
    jinja
+   io
+   docker

docs/source/standardlib/io.rst

@@ -0,0 +1,19 @@
+IO
+==
+
+ArchivePackagingBaseTask
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. jinja:: ArchivePackagingBaseTask
+   :file: source/templates/package-usage.rst
+
+.. CAUTION::
+    This is a Base Task. It is not a Task to run, but to create a **own, runnable Task** basing on it.
+
+.. HINT::
+    This is an extendable task. Read more in :ref:`Extending tasks` chapter.
+
+
+.. autoclass:: rkd.core.standardlib.io.ArchivePackagingBaseTask
+   :exclude-members: get_name, get_group_name
+   :members:

docs/source/standardlib/php.rst

@@ -0,0 +1,23 @@
+PHP
+===
+
+PhpScriptTask
+~~~~~~~~~~~~~
+
+- configure: Should be overridden only with @before_parent decorator
+- inner_execute: Should be overridden preserving original parent after or before
+- input: A string of PHP code, optionally
+
+.. jinja:: PhpScriptTask
+   :file: source/templates/package-usage.rst
+
+.. CAUTION::
+    This is a Base Task. It is not a Task to run, but to create a **own, runnable Task** basing on it.
+
+.. HINT::
+    This is an extendable task. Read more in :ref:`Extending tasks` chapter.
+
+
+.. autoclass:: rkd.php.script.PhpScriptTask
+   :exclude-members: get_name, get_group_name
+   :members:

docs/source/standardlib/shell.rst

@@ -11,7 +11,11 @@ Provides tasks for shell commands execution - mostly used in YAML syntax and in
 
 Executes a Bash script. Can be multi-line.
 
-*Notice: phrase %RKD% is replaced with an rkd binary name*
+.. HINT::
+    Phrase %RKD% is replaced with an rkd binary name
+
+.. HINT::
+    This is an extendable task. Read more in :ref:`Extending tasks` chapter.
 
 **Example of plain usage:**
 

docs/source/standardlib/technical.rst

@@ -49,6 +49,9 @@ to create a task by defining a simple method as a callback.
 :rkd:create-structure
 ~~~~~~~~~~~~~~~~~~~~~
 
+.. HINT::
+    This is an extendable task. Read more in :ref:`Extending tasks` chapter.
+
 .. jinja:: rkd_create_structure
    :file: source/templates/package-usage.rst
 

src/core/rkd/core/standardlib/io.py

@@ -20,6 +20,22 @@ class ArchivePackagingBaseTask(ExtendableTaskInterface):
       - dry-run mode (do not write anything to disk, just print messages)
       - copies directories recursively
       - .gitignore files support (manually added using API method)
+
+
+    Example:
+
+        .. code:: python
+
+            @extends(ArchivePackagingBaseTask)
+            def PackIntoZipTask():
+                def configure(task: ArchivePackagingBaseTask, event: ConfigurationLifecycleEvent):
+                    task.archive_path = '/tmp/test-archive.zip'
+                    task.consider_gitignore('.gitignore')
+                    task.add('tests/samples/', './')
+
+                return [configure]
+
+
     """
 
     sources: Dict[str, str]

src/php/MANIFEST.in

@@ -0,0 +1,5 @@
+recursive-exclude tests *
+recursive-exclude example *
+include requirements-external.txt
+include requirements-subpackages.txt
+include setup.json

src/php/pyproject.toml

@@ -0,0 +1,2 @@
+[build-system]
+requires = ["setuptools>=45", "wheel", "riotkit.pbs>=1"]

src/php/requirements-external.txt

@@ -0,0 +1 @@
+riotkit.pbs >= 1.0

src/php/rkd/php/script.py

@@ -21,6 +21,26 @@ class PhpScriptTask(RunInContainerBaseTask):
         script: Path to script to load instead of stdin (could be a relative path)
         version: PHP version. Leave None to use default 8.0-alpine version
 
+    Example of usage:
+
+        .. code:: yaml
+
+            version: org.riotkit.rkd/yaml/v1
+            imports:
+                - rkd.php.script.PhpScriptTask
+
+            tasks:
+                :yaml:test:php:
+                    extends: rkd.php.script.PhpScriptTask
+                    configure@before_parent: |
+                        self.version = '7.2-alpine'
+                    inner_execute@after_parent: |
+                        print('IM AFTER PARENT')
+                        return True
+                    input: |
+                        var_dump(getcwd());
+                        var_dump(phpversion());
+
     """
 
     script: Optional[str]

src/php/setup.json

@@ -0,0 +1,19 @@
+{
+    "name": "rkd.php",
+    "author": "RiotKit non-profit organization",
+    "author_email": "riotkit@riseup.net",
+    "description": "rkd.php adds support for PHP language in Riotkit-Do",
+    "url": "https://github.com/riotkit-org",
+    "license": "Apache-2",
+    "classifiers": [
+        "Development Status :: 5 - Production/Stable",
+        "Environment :: Console",
+        "Intended Audience :: Developers",
+        "Intended Audience :: System Administrators",
+        "Intended Audience :: Information Technology",
+        "License :: OSI Approved :: Apache Software License",
+        "Operating System :: POSIX",
+        "Programming Language :: Python :: 3 :: Only"
+    ],
+    "keywords": ["rkd", "riotkit", "anarchism", "php"]
+}

src/php/setup.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+
+from riotkit.pbs import get_setup_attributes
+from setuptools import setup, find_namespace_packages
+
+setup(
+    **get_setup_attributes(root_dir='./', git_root_dir='../../'),
+    packages=find_namespace_packages(include='rkd.*', exclude=('tests',)),
+)

src/php/tests/samples/.rkd/makefile.py

@@ -43,8 +43,8 @@ def PackIntoZipTask():
 
     def configure(task: ArchivePackagingBaseTask, event: ConfigurationLifecycleEvent):
         task.archive_path = '/tmp/test-archive.zip'
-        task.consider_gitignore('/home/krzysiek/Projekty/riotkit/riotkit/rkd/.gitignore')
-        task.add('/home/krzysiek/Projekty/riotkit/riotkit/rkd/src/php/tests/samples/', './')
+        task.consider_gitignore('.gitignore')
+        task.add('tests/samples/', './')
 
     return [configure]