From 05188f43f212f74398de47550c395cdedaf5ecd4 Mon Sep 17 00:00:00 2001 From: Yota Hamada Date: Tue, 1 Oct 2024 22:36:45 +0900 Subject: [PATCH] docs: Add docs for special envs (#689) --- docs/docs.egg-info/PKG-INFO | 42 ++++++++++++++++++++++++---------- docs/docs.egg-info/SOURCES.txt | 1 + docs/source/index.rst | 1 + docs/source/special_env.rst | 34 +++++++++++++++++++++++++++ 4 files changed, 66 insertions(+), 12 deletions(-) create mode 100644 docs/source/special_env.rst diff --git a/docs/docs.egg-info/PKG-INFO b/docs/docs.egg-info/PKG-INFO index 55b948fc8..a54b7e3ae 100644 --- a/docs/docs.egg-info/PKG-INFO +++ b/docs/docs.egg-info/PKG-INFO @@ -5,38 +5,45 @@ Summary: Documentation for Dagu Author-email: Yota Hamada Requires-Python: >=3.11 Description-Content-Type: text/markdown +License-File: LICENSE Requires-Dist: sphinx==5.3.0 Requires-Dist: sphinx-rtd-theme==2.0.0 Requires-Dist: sphinx-autobuild>=2024.4.16 Requires-Dist: sphinx-intl>=2.2.0 # Dagu Documentation + This is the documentation for the Dagu project. ## Prerequisites + Make sure you have the following installed: -- Python (version >= 3.11) -- Rye +- Python (version >= 3.11) +- Rye ## Getting Started 1. Clone the repository: + ```sh git clone https://github.com/dagu-org/dagu.git ``` 2. Navigate to the document directory: + ```sh cd docs ``` 3. Install the project dependencies using Rye: + ```sh rye sync ``` ## Running Locally + To run the documentation server locally, use the following command: ```sh @@ -47,14 +54,17 @@ This will start the sphinx-autobuild server, which will watch for changes in the Open your web browser and visit http://localhost:8000 to view the documentation. ## Building the Documentation + To build the documentation, use one of the following commands: -- For English documentation: +- For English documentation: + ```sh rye run build ``` -- For Japanese documentation: +- For Japanese documentation: + ```sh rye run build-ja ``` @@ -62,6 +72,7 @@ rye run build-ja The built documentation will be available in the build/html directory. ## Generating Gettext Files (Japanese) + To generate the gettext files for Japanese translation, run: ```shell @@ -76,23 +87,30 @@ We welcome contributions for adding new translations to the documentation. To ad 1. Create a new directory for the target language in the `source/locale` directory (e.g., `source/locale/fr` for French). 2. Generate the gettext files for the target language by running: + ```shell -sphinx-build -b gettext source/ build/locale +make gettext +sphinx-intl update -p build/gettext -l ``` -3. Update the translation files in the source/locale//LC_MESSAGES directory. -4. Build the documentation for the target language: + +Replace `` with the appropriate language code (e.g., `fr` for French). 3. Update the translation files in the source/locale//LC_MESSAGES directory. 4. Build the documentation for the target language: + ```shell sphinx-build -b html -D language= source/ build/html/ ``` -Replace `` with the appropriate language code (e.g., `fr` for French). -5. Submit a pull request with your changes. + +Replace `` with the appropriate language code (e.g., `fr` for French). 5. Submit a pull request with your changes. + +See [Sphinx Internationalization](https://www.sphinx-doc.org/en/master/usage/advanced/intl.html) for more information on internationalization in Sphinx. ## Dependencies + The project dependencies are managed using Rye and specified in the `pyproject.toml` file. The main dependencies include: -- Sphinx (version 5.3.0) -- sphinx-rtd-theme (version 2.0.0) -- sphinx-autobuild (version >= 2024.4.16) +- Sphinx (version 5.3.0) +- sphinx-rtd-theme (version 2.0.0) +- sphinx-autobuild (version >= 2024.4.16) ## Contributing + We welcome contributions to improve the documentation. If you find any issues or have suggestions for enhancements, please feel free to open an issue or submit a pull request. diff --git a/docs/docs.egg-info/SOURCES.txt b/docs/docs.egg-info/SOURCES.txt index 034db04c3..2cc2f0dde 100644 --- a/docs/docs.egg-info/SOURCES.txt +++ b/docs/docs.egg-info/SOURCES.txt @@ -1,3 +1,4 @@ +LICENSE README.md pyproject.toml docs.egg-info/PKG-INFO diff --git a/docs/source/index.rst b/docs/source/index.rst index 981f48ca3..c07a38e91 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -68,6 +68,7 @@ Quick Start executors base_config examples + special_env .. toctree:: :caption: Configuration diff --git a/docs/source/special_env.rst b/docs/source/special_env.rst new file mode 100644 index 000000000..6da008565 --- /dev/null +++ b/docs/source/special_env.rst @@ -0,0 +1,34 @@ +.. _Special Environment Variables: + +Special Environment Variables +============================== + +.. contents:: + :local: + +Inside a DAG, you can use the following environment variables to access special values: + +- ``DAG_EXECUTION_LOG_PATH``: The path to the log file for the current step. +- ``DAG_SCHEDULER_LOG_PATH``: The path to the log file for the scheduler. +- ``DAG_REQUEST_ID``: The unique ID for the current execution request. + +Example Usage +~~~~~~~~~~~~~ + +.. code-block:: yaml + + steps: + - name: print values + command: bash + script: | + echo DAG_EXECUTION_LOG_PATH=$DAG_EXECUTION_LOG_PATH + echo DAG_SCHEDULER_LOG_PATH=$DAG_SCHEDULER_LOG_PATH + echo DAG_REQUEST_ID=$DAG_REQUEST_ID + +**Example Output** + +.. code-block:: bash + + DAG_EXECUTION_LOG_PATH=/path/to/logs/special-envs/step1.20241001.22:31:29.167.0cf64f67.log + DAG_SCHEDULER_LOG_PATH=/path/to/logs/special-envs/start_special-envs.20241001.22:31:29.163.0cf64f67.log + DAG_REQUEST_ID=0cf64f67-a1d6-4764-b5e0-0ea92c3089e2