Documentation

FirebirdSQL · Mar 27, 2023 · c35a763 · c35a763
1 parent 5ad1bc6
commit c35a763
Show file tree

Hide file tree

Showing 222 changed files with 48,116 additions and 17,227 deletions.
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -0,0 +1,33 @@
+#########
+Changelog
+#########
+
+Version 0.8.0
+=============
+
+* Milestone 5.
+
+  Saturnin can now be considered as early beta. There will be more additions, extensions
+  and improvements before the 1.0 release, but the platform is almost feature-complete and
+  the functionality provided is considered stable and ready for testing. However, some
+  backwards incompatible changes in future releases are still possible.
+
+Unreleased versions 0.7.1 - 0.7.12
+==================================
+
+* Milestones 3 and 4.
+
+Version 0.7.0
+=============
+
+* Milestone 2
+
+Version 0.1.0
+=============
+
+Initial release.
+
+.. _saturnin: https://pypi.org/project/firebird-lib/
+.. _releases: https://github.com/FirebirdSQL/python3-driver/releases
+.. _Dash: https://kapeli.com/dash
+.. _Zeal: https://zealdocs.org/
diff --git a/docs/changelog.txt b/docs/changelog.txt
diff --git a/docs/conf.py b/docs/conf.py
@@ -51,7 +51,7 @@
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.txt'
+source_suffix = '.rst'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

diff --git a/docs/getting-started.rst b/docs/getting-started.rst
@@ -0,0 +1,116 @@
+
+###############
+Getting Started
+###############
+
+Installation
+************
+
+You will need Python v3.8 or later to install Saturnin.
+
+For regular deployments, we recommend installing using the pipx_ tool, which installs into
+a separate virtual Python environment and exposes all executable commands in the search path.
+
+::
+
+  > pip install pipx
+  > pipx install saturnin
+
+If you want to develop your own services using the Saturnin SDK, we recommend that you
+first create a separate virtual environment into which you install Saturnin in the usual
+way with the pip_ tool.
+
+Initialization
+**************
+
+Saturnin uses a number of files and directories whose location in the file system corresponds
+to the standards for the platform on which it is installed. This basic directory placement
+scheme can be changed by using the `SATURNIN_HOME` environment variable, which sets the root
+of the other directory locations. Alternatively, you can create a `"home"` subdirectory in
+the root directory of the virtual environment in which Saturnin is isolated.
+
+.. important::
+
+   Because on Linux or MacOS the default location of some directories may require higher
+   than normal access rights, we recommend that you always use the home directory setting
+   on these platforms.
+
+.. tip::
+
+   To set the home directory in the virtual environment (recommended when installing with
+   pipx_), use the command::
+
+     > saturnin create home
+
+The next step is to initialize the Saturnin installation with the command::
+
+   > saturnin initialize
+
+Saturnin console
+****************
+
+The `saturnin` tool is used to manage the Saturnin platform installation. It can be operated
+in two modes:
+
+- **Single command (direct) mode.** The required command and parameters are entered directly on
+  the command line, and after the command is executed, the tool is terminated.
+
+- **Interactive console mode** activated by running the tool without additional parameters.
+  The interactive console offers an enhanced command line with persistent command history,
+  command and parameter completion, and interactive help.
+
+.. note::
+
+   The command set available in console mode differs from command set available in direct mode,
+   as some commands (typically those required to run only once or not very often like initialize
+   or create home) are available only in direct mode.
+
+For normal work, we recommend using the interactive console mode. In the following sections,
+all the commands described are entered in the interactive console.
+
+Installing services
+*******************
+
+Immediately after installation, Saturnin does not provide any Butler services. These
+services need to be installed separately. Although you can install service packages with
+the standard pip utility, we recommend that you use saturnin's `install package`,
+`uninstall package`, and `pip` commands to install, uninstall, or manage service packages,
+as these commands also update the necessary registries that Saturnin uses to work with
+Butler services and Saturnin applications.
+
+.. note::
+
+   If necessary, the command: `update registry` can be used to update the registries.
+
+To install package with Saturnin core services, use command::
+
+   > install package saturnin-core
+
+Using Firebird services
+***********************
+
+To use Butler services that work with Firebird server, you need to create (and update)
+a configuration file for the firebird driver using the commands::
+
+   > create config firebird
+   > edit config firebird
+
+Saturnin recipes
+****************
+
+Recipes are Saturnin-specific configuration files with instructions for running Butler
+services built for Saturnin. Recipes can be created with the create recipe command, which
+creates a recipe template that typically needs to be modified further (because it only
+contains default values). Recipes created independently (e.g. by a solution supplier or
+provided by installed Saturnin application) must be installed with the `install recipe` command.
+
+Created or installed recipes can be run with the `run recipe-name` command. You can get
+a list of recipes that can be started with the `list recipes` command.
+
+.. seealso::
+
+   For more information, see the :doc:`Usage Guide <usage-guide>`.
+
+.. _PYPI: https://pypi.org/
+.. _pip: https://pypi.org/project/pip/
+.. _pipx: https://pypa.github.io/pipx/
diff --git a/docs/getting-started.txt b/docs/getting-started.txt
diff --git a/docs/index.txt → docs/index.rst b/docs/index.txt → docs/index.rst
@@ -1,29 +1,29 @@
 
-########
-Saturnin
-########
-
-Saturnin is an implementation of Firebird Butler platform for Python.
+#####################################################
+Saturnin - The `Firebird Butler`_ platform for Python
+#####################################################
 
 .. note:: Requires Python 3.8+
 
 .. tip:: You can download docset for Dash_ (MacOS) or Zeal_ (Windows / Linux) documentation
    readers from releases_ at github.
 
-Content
-*******
+Saturnin development is sponsored by IBPhoenix_.
 
 .. toctree::
    :maxdepth: 1
+   :hidden:
 
-   getting-started
    usage-guide
    reference
    changelog
    license
 
-Saturnin development is sponsored by IBPhoenix_.
+|
+|
+|
 
+.. include:: getting-started.rst
 
 .. _IBPhoenix: http://www.ibphoenix.com
 .. _Python: http://python.org
@@ -33,3 +33,4 @@ Saturnin development is sponsored by IBPhoenix_.
 .. _releases: https://github.com/FirebirdSQL/saturnin/releases
 .. _Dash: https://kapeli.com/dash
 .. _Zeal: https://zealdocs.org/
+.. _Firebird Butler: https://firebird-butler.readthedocs.io
diff --git a/docs/license.txt → docs/license.rst b/docs/license.txt → docs/license.rst
diff --git a/docs/ref-base-component.txt → docs/ref-base-component.rst b/docs/ref-base-component.txt → docs/ref-base-component.rst
diff --git a/docs/ref-base-config.txt → docs/ref-base-config.rst b/docs/ref-base-config.txt → docs/ref-base-config.rst
diff --git a/docs/ref-base-transport.txt → docs/ref-base-transport.rst b/docs/ref-base-transport.txt → docs/ref-base-transport.rst
diff --git a/docs/ref-base-types.txt → docs/ref-base-types.rst b/docs/ref-base-types.txt → docs/ref-base-types.rst
diff --git a/docs/ref-base.txt → docs/ref-base.rst b/docs/ref-base.txt → docs/ref-base.rst
diff --git a/docs/ref-component-apps.txt → docs/ref-component-apps.rst b/docs/ref-component-apps.txt → docs/ref-component-apps.rst
diff --git a/docs/ref-component-bundle.txt → docs/ref-component-bundle.rst b/docs/ref-component-bundle.txt → docs/ref-component-bundle.rst
diff --git a/docs/ref-component-client.txt → docs/ref-component-client.rst b/docs/ref-component-client.txt → docs/ref-component-client.rst
diff --git a/docs/ref-component-controller.txt → docs/ref-component-controller.rst b/docs/ref-component-controller.txt → docs/ref-component-controller.rst
diff --git a/docs/ref-component-micro.txt → docs/ref-component-micro.rst b/docs/ref-component-micro.txt → docs/ref-component-micro.rst
diff --git a/docs/ref-component-recipe.txt → docs/ref-component-recipe.rst b/docs/ref-component-recipe.txt → docs/ref-component-recipe.rst
diff --git a/docs/ref-component-registry.txt → docs/ref-component-registry.rst b/docs/ref-component-registry.txt → docs/ref-component-registry.rst
diff --git a/docs/ref-component-service.txt → docs/ref-component-service.rst b/docs/ref-component-service.txt → docs/ref-component-service.rst
diff --git a/docs/ref-component-single.txt → docs/ref-component-single.rst b/docs/ref-component-single.txt → docs/ref-component-single.rst
diff --git a/docs/ref-lib-console.txt → docs/ref-lib-console.rst b/docs/ref-lib-console.txt → docs/ref-lib-console.rst
diff --git a/docs/ref-lib-daemon.txt → docs/ref-lib-daemon.rst b/docs/ref-lib-daemon.txt → docs/ref-lib-daemon.rst
diff --git a/docs/ref-lib-data-filter.txt → docs/ref-lib-data-filter.rst b/docs/ref-lib-data-filter.txt → docs/ref-lib-data-filter.rst
diff --git a/docs/ref-lib-data-onepipe.txt → docs/ref-lib-data-onepipe.rst b/docs/ref-lib-data-onepipe.txt → docs/ref-lib-data-onepipe.rst
diff --git a/docs/ref-lib-metadata.txt → docs/ref-lib-metadata.rst b/docs/ref-lib-metadata.txt → docs/ref-lib-metadata.rst
diff --git a/docs/ref-protocol-fbdp.txt → docs/ref-protocol-fbdp.rst b/docs/ref-protocol-fbdp.txt → docs/ref-protocol-fbdp.rst
diff --git a/docs/ref-protocol-fbsp.txt → docs/ref-protocol-fbsp.rst b/docs/ref-protocol-fbsp.txt → docs/ref-protocol-fbsp.rst
diff --git a/docs/ref-protocol-iccp.txt → docs/ref-protocol-iccp.rst b/docs/ref-protocol-iccp.txt → docs/ref-protocol-iccp.rst
diff --git a/docs/ref-scripts-bundlerun.txt → docs/ref-scripts-bundlerun.rst b/docs/ref-scripts-bundlerun.txt → docs/ref-scripts-bundlerun.rst
diff --git a/docs/ref-scripts-cli.txt → docs/ref-scripts-cli.rst b/docs/ref-scripts-cli.txt → docs/ref-scripts-cli.rst
diff --git a/docs/ref-scripts-commands-daemons.txt → docs/ref-scripts-commands-daemons.rst b/docs/ref-scripts-commands-daemons.txt → docs/ref-scripts-commands-daemons.rst
diff --git a/docs/ref-scripts-commands-oids.txt → docs/ref-scripts-commands-oids.rst b/docs/ref-scripts-commands-oids.txt → docs/ref-scripts-commands-oids.rst
diff --git a/docs/ref-scripts-commands-pkg.txt → docs/ref-scripts-commands-pkg.rst b/docs/ref-scripts-commands-pkg.txt → docs/ref-scripts-commands-pkg.rst
diff --git a/docs/ref-scripts-commands-recipes.txt → docs/ref-scripts-commands-recipes.rst b/docs/ref-scripts-commands-recipes.txt → docs/ref-scripts-commands-recipes.rst
diff --git a/docs/ref-scripts-commands-site.txt → docs/ref-scripts-commands-site.rst b/docs/ref-scripts-commands-site.txt → docs/ref-scripts-commands-site.rst
diff --git a/docs/ref-scripts-completers.txt → docs/ref-scripts-completers.rst b/docs/ref-scripts-completers.txt → docs/ref-scripts-completers.rst
diff --git a/docs/ref-scripts-daemon.txt → docs/ref-scripts-daemon.rst b/docs/ref-scripts-daemon.txt → docs/ref-scripts-daemon.rst
diff --git a/docs/ref-scripts-repl.txt → docs/ref-scripts-repl.rst b/docs/ref-scripts-repl.txt → docs/ref-scripts-repl.rst
diff --git a/docs/ref-scripts-svcrun.txt → docs/ref-scripts-svcrun.rst b/docs/ref-scripts-svcrun.txt → docs/ref-scripts-svcrun.rst
diff --git a/docs/reference.txt → docs/reference.rst b/docs/reference.txt → docs/reference.rst
diff --git a/docs/requirements.txt → docs/requirements.rst b/docs/requirements.txt → docs/requirements.rst
diff --git a/docs/saturnin.docset/Contents/Resources/Documents/.buildinfo b/docs/saturnin.docset/Contents/Resources/Documents/.buildinfo
@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 60c841d4059dfa049b1567bcbad4f808
+config: 7d8a4922aaeae69ea1bde7dc669170fc
 tags: 645f666f9bcd5a90fca523b33c5a78b7