sphinx-autodoc2

https://github.com/sphinx-extensions2/sphinx-autodoc2
Admin
sphinx-autodoc2 is a Sphinx extension that automatically generates API documentation for Python...
Tokens:100,439
Snippets:356
Trust Score:6
License:MIT
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install sphinx-autodoc2 using pip

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/quickstart.md

Installs the sphinx-autodoc2 package from PyPI. This is the first step to using the extension.

```bash
pip install sphinx-autodoc2
```

--------------------------------

### Installing sphinx-autodoc2 with CLI Extra

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/quickstart.md

This command installs `sphinx-autodoc2` with the 'cli' extra, which includes the `autodoc2` command-line tool. This tool can be used for various documentation generation tasks.

```bash
pip install sphinx-autodoc2[cli]

```

--------------------------------

### Setup Function

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/autodoc2/autodoc2.sphinx.extension.rst

The setup function is the entry point for the Sphinx extension. It initializes the extension and adds necessary event handlers.

```APIDOC
## POST /setup

### Description
Initializes the autodoc2 Sphinx extension and configures Sphinx application.

### Method
POST

### Endpoint
/setup

### Parameters
#### Query Parameters
- **app** (sphinx.application.Sphinx) - Required - The Sphinx application instance.

### Request Body
None

### Response
#### Success Response (200)
- **return_value** (dict[str, str | bool]) - A dictionary containing extension configuration or status.

#### Response Example
{
  "return_value": {
    "version": "1.0",
    "parallel_read_safe": true
  }
}
```

--------------------------------

### DaemonClient Methods

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.engine.rst

Documentation for methods within the DaemonClient class, including starting the daemon and awaiting conditions.

```APIDOC
## DaemonClient Methods

### Description
Provides documentation for methods related to the AIIDA daemon client, such as starting the daemon and managing its state.

### Methods

#### `start_daemon()`

##### Description
Starts the AIIDA daemon.

##### Method
`start_daemon`

##### Endpoint
N/A (Internal method)

#### `_await_condition(condition: typing.Callable, exception: Exception, timeout: int = 5, interval: float = 0.1)`

##### Description
Waits for a specific condition to be met, with optional timeout and interval.

##### Method
`_await_condition`

##### Endpoint
N/A (Internal method)

##### Parameters

###### Path Parameters
None

###### Query Parameters
None

###### Request Body
None

##### Request Example
None

##### Response

###### Success Response (200)
None (returns implicitly upon condition met or timeout)

###### Response Example
None

#### `_start_daemon(number_workers: int = 1, foreground: bool = False)`

##### Description
Starts the daemon with a specified number of workers and foreground option.

##### Method
`_start_daemon`

##### Endpoint
N/A (Internal method)

##### Parameters

###### Path Parameters
None

###### Query Parameters
None

###### Request Body
None

##### Request Example
None

##### Response

###### Success Response (200)
None

###### Response Example
None
```

--------------------------------

### Enable sphinx-autodoc2 in conf.py

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/quickstart.md

Enables the 'autodoc2' extension and configures the packages to be documented. This is a minimum requirement for the extension to function.

```python
extensions = [
    "autodoc2",
]
autodoc2_packages = [
    "../my_package",
]
```

--------------------------------

### Displaying Help for autodoc2 Command Line Tool

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/quickstart.md

This command displays the help message for the `autodoc2` command-line tool, providing information on its available subcommands and options.

```bash
autodoc2 --help

```

--------------------------------

### Configuring Module-Specific Markdown Rendering with autodoc2_render_plugin_regexes

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/quickstart.md

This configuration in `conf.py` allows specifying which modules should be rendered using the 'myst' plugin. The example `(r"autodoc2\.db", "myst")` ensures that the `autodoc2.db` module is processed using MyST Markdown.

```python
autodoc2_render_plugin_regexes = [
    (r"autodoc2\.db", "myst")
]

```

--------------------------------

### Disable auto mode for specific packages in conf.py

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/quickstart.md

Disables the automatic documentation generation for a specific package, allowing for manual documentation. This is useful when you want more control over what gets documented.

```python
extensions = [
    "autodoc2",
]
autodoc2_packages = [
    {
        "path": "../my_package",
        "auto_mode": False,
    },
]
```

--------------------------------

### Documenting Public API with __all__ in Python

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/quickstart.md

This snippet demonstrates how to use the `__all__` variable in Python to explicitly define the public API of a module. It specifies which objects should be documented by `sphinx-autodoc2`. This helps in controlling the visibility of your package's API.

```python
from .my_module import MyClass
__all__ = [
    "MyClass",
    "my_function",
]
def my_function(): ...

```

--------------------------------

### Run Linters and Formatters with Pre-commit

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/README.md

This command uses pre-commit, a framework for managing and executing pre-commit hooks, to run all configured linters and formatters across the project files. Pre-commit needs to be installed via pipx. The 'pre-commit install' command sets up the git hook.

```bash
pipx install pre-commit
pre-commit run --all-files
# pre-commit install
```

--------------------------------

### Example autodoc_db.json Structure

Source: https://context7.com/sphinx-extensions2/sphinx-autodoc2/llms.txt

Provides an example structure of the JSON database file generated by `autodoc2 create-db`. This file contains analyzed information about Python packages and their items, including types, names, docstrings, and file paths.

```json
{
  "items": {
    "mypackage": {
      "type": "package",
      "full_name": "mypackage",
      "doc": "Main package docstring.",
      "file_path": "/path/to/mypackage/__init__.py",
      "all": ["MyClass", "process_data"]
    },
    "mypackage.MyClass": {
      "type": "class",
      "full_name": "mypackage.MyClass",
      "doc": "A sample class.",
      "bases": ["object"],
      "range": [10, 50]
    }
  },
  "overloads": {}
}
```

--------------------------------

### Configuring autodoc2_module_all_regexes in conf.py

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/quickstart.md

This configuration snippet for `conf.py` enables the feature to document only the public API as defined by `__all__`. The regular expression `r"my_package\..*"` ensures that this behavior is applied to all modules within `my_package`.

```python
autodoc2_module_all_regexes = [
    r"my_package\..*",
]

```

--------------------------------

### Enabling MyST Field Lists Extension in conf.py

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/quickstart.md

This configuration enables the 'fieldlist' extension for MyST Markdown parser in `conf.py`. This is necessary for using Sphinx-style field lists within Markdown docstrings, providing structured documentation elements.

```python
myst_enable_extensions = ["fieldlist"]

```

--------------------------------

### Replace annotations and bases for intersphinx warnings in conf.py

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/quickstart.md

Configures sphinx-autodoc2 to replace specific type annotations and class bases with correct references, resolving 'reference target not found' warnings. This is useful when dealing with external packages and intersphinx inventories.

```python
autodoc2_replace_annotations = {
    "package.MyClass": "package.module.MyClass",
}
autodoc2_replace_bases = {
    "package.MyClass": "package.module.MyClass",
}
```

--------------------------------

### Configuring Markdown Docstring Parsing with autodoc2_docstring_parser_regexes

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/quickstart.md

This configuration in `conf.py` allows `sphinx-autodoc2` to interpret docstrings as Markdown (MyST) for specific modules or all modules. The `(r".*", "myst")` pattern renders all docstrings as Markdown, while `(r"autodoc2\..*", "myst")` targets only modules within the `autodoc2` package.

```python
autodoc2_docstring_parser_regexes = [
    # this will render all docstrings as Markdown
    (r".*", "myst"),
    # this will render select docstrings as Markdown
    (r"autodoc2\..*", "myst"),
]

```

--------------------------------

### Documenting aiida.orm.groups.Group Methods and Properties

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.orm.rst

This snippet demonstrates how sphinx-autodoc2 is used to document various methods and properties of the aiida.orm.groups.Group class. It includes examples for attributes like _type_string, _CLS_COLLECTION, and methods such as base(), __repr__(), __str__(), store(), entry_point(), count(), clear(), add_nodes(), remove_nodes(), and is_user_defined(). It also documents properties like uuid, label, description, type_string, user, nodes, and is_empty.

```python
.. autodoc2-docstring:: aiida.orm.groups.Group._type_string

.. py:attribute:: _CLS_COLLECTION
   :canonical: aiida.orm.groups.Group._CLS_COLLECTION
   :value: None

   .. autodoc2-docstring:: aiida.orm.groups.Group._CLS_COLLECTION

.. py:method:: base() -> aiida.orm.groups.GroupBase
   :canonical: aiida.orm.groups.Group.base

   .. autodoc2-docstring:: aiida.orm.groups.Group.base

.. py:method:: __repr__() -> str
   :canonical: aiida.orm.groups.Group.__repr__

   .. autodoc2-docstring:: aiida.orm.groups.Group.__repr__

.. py:method:: __str__() -> str
   :canonical: aiida.orm.groups.Group.__str__

   .. autodoc2-docstring:: aiida.orm.groups.Group.__str__

.. py:method:: store() -> aiida.orm.groups.SelfType
   :canonical: aiida.orm.groups.Group.store

   .. autodoc2-docstring:: aiida.orm.groups.Group.store

.. py:method:: entry_point() -> typing.Optional[aiida.plugins.entry_point.EntryPoint]
   :canonical: aiida.orm.groups.Group.entry_point

   .. autodoc2-docstring:: aiida.orm.groups.Group.entry_point

.. py:property:: uuid
   :canonical: aiida.orm.groups.Group.uuid
   :type: str

   .. autodoc2-docstring:: aiida.orm.groups.Group.uuid

.. py:property:: label
   :canonical: aiida.orm.groups.Group.label
   :type: str

   .. autodoc2-docstring:: aiida.orm.groups.Group.label

.. py:property:: description
   :canonical: aiida.orm.groups.Group.description
   :type: str

   .. autodoc2-docstring:: aiida.orm.groups.Group.description

.. py:property:: type_string
   :canonical: aiida.orm.groups.Group.type_string
   :type: str

   .. autodoc2-docstring:: aiida.orm.groups.Group.type_string

.. py:property:: user
   :canonical: aiida.orm.groups.Group.user
   :type: aiida.orm.User

   .. autodoc2-docstring:: aiida.orm.groups.Group.user

.. py:method:: count() -> int
   :canonical: aiida.orm.groups.Group.count

   .. autodoc2-docstring:: aiida.orm.groups.Group.count

.. py:property:: nodes
   :canonical: aiida.orm.groups.Group.nodes
   :type: aiida.orm.convert.ConvertIterator

   .. autodoc2-docstring:: aiida.orm.groups.Group.nodes

.. py:property:: is_empty
   :canonical: aiida.orm.groups.Group.is_empty
   :type: bool

   .. autodoc2-docstring:: aiida.orm.groups.Group.is_empty

.. py:method:: clear() -> None
   :canonical: aiida.orm.groups.Group.clear

   .. autodoc2-docstring:: aiida.orm.groups.Group.clear

.. py:method:: add_nodes(nodes: typing.Union[aiida.orm.nodes.Node, typing.Sequence[aiida.orm.nodes.Node]]) -> None
   :canonical: aiida.orm.groups.Group.add_nodes

   .. autodoc2-docstring:: aiida.orm.groups.Group.add_nodes

.. py:method:: remove_nodes(nodes: typing.Union[aiida.orm.nodes.Node, typing.Sequence[aiida.orm.nodes.Node]]) -> None
   :canonical: aiida.orm.groups.Group.remove_nodes

   .. autodoc2-docstring:: aiida.orm.groups.Group.remove_nodes

.. py:method:: is_user_defined() -> bool
   :canonical: aiida.orm.groups.Group.is_user_defined

   .. autodoc2-docstring:: aiida.orm.groups.Group.is_user_defined

.. py:attribute:: _deprecated_extra_methods
   :canonical: aiida.orm.groups.Group._deprecated_extra_methods
   :value: None

   .. autodoc2-docstring:: aiida.orm.groups.Group._deprecated_extra_methods

.. py:method:: __getattr__(name: str) -> typing.Any
   :canonical: aiida.orm.groups.Group.__getattr__

   .. autodoc2-docstring:: aiida.orm.groups.Group.__getattr__
```

--------------------------------

### Documenting InstalledCode Class with Sphinx-autodoc2

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.orm.rst

This snippet demonstrates the documentation of the InstalledCode class using sphinx-autodoc2. It shows the class definition, its inheritance from aiida.orm.nodes.data.code.legacy.Code, and its constructor parameters.

```python
.. py:class:: InstalledCode(computer: aiida.orm.Computer, filepath_executable: str, **kwargs)
   :canonical: aiida.orm.nodes.data.code.installed.InstalledCode

   Bases: :py:obj:`aiida.orm.nodes.data.code.legacy.Code`
```

--------------------------------

### Computer Class Methods

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.orm.rst

This section covers various methods for managing computer configurations, including settings for double quotes, MPI run commands, default processors and memory per machine, job poll intervals, work directories, and shebang lines.

```APIDOC
## Computer Class Methods

### Description
Provides methods to get and set various configuration parameters for a computer.

### Methods

- **get_use_double_quotes()**: Retrieves the setting for using double quotes.
- **set_use_double_quotes(val: bool)**: Sets the preference for using double quotes.
- **get_mpirun_command()**: Retrieves the MPI run command.
- **set_mpirun_command(val: typing.Union[typing.List[str], typing.Tuple[str, ...]])**: Sets the MPI run command.
- **get_default_mpiprocs_per_machine()**: Retrieves the default number of MPI processes per machine.
- **set_default_mpiprocs_per_machine(def_cpus_per_machine: typing.Optional[int])**: Sets the default number of MPI processes per machine.
- **get_default_memory_per_machine()**: Retrieves the default memory per machine.
- **set_default_memory_per_machine(def_memory_per_machine: typing.Optional[int])**: Sets the default memory per machine.
- **get_minimum_job_poll_interval()**: Retrieves the minimum job poll interval.
- **set_minimum_job_poll_interval(interval: float)**: Sets the minimum job poll interval.
- **get_workdir()**: Retrieves the working directory.
- **set_workdir(val: str)**: Sets the working directory.
- **get_shebang()**: Retrieves the shebang line.
- **set_shebang(val: str)**: Sets the shebang line.

### Request Example
```python
# Example for set_use_double_quotes
computer.set_use_double_quotes(True)

# Example for set_mpirun_command
computer.set_mpirun_command(['mpiexec', '-n'])

# Example for set_default_mpiprocs_per_machine
computer.set_default_mpiprocs_per_machine(16)

# Example for set_default_memory_per_machine
computer.set_default_memory_per_machine(8192)

# Example for set_minimum_job_poll_interval
computer.set_minimum_job_poll_interval(0.5)

# Example for set_workdir
computer.set_workdir('/path/to/workdir')

# Example for set_shebang
computer.set_shebang('#!/bin/bash')
```

### Response
All setter methods return None upon successful execution.

#### Success Response (200)
- **None**: Indicates the operation was successful.
```

--------------------------------

### Get Git Clone Function

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/autodoc2/autodoc2.sphinx.extension.rst

Utility function to clone a Git repository, useful for fetching source code for documentation.

```APIDOC
## POST /get_git_clone

### Description
Clones a Git repository from a given URL and branch/tag.

### Method
POST

### Endpoint
/get_git_clone

### Parameters
#### Query Parameters
- **app** (sphinx.application.Sphinx) - Required - The Sphinx application instance.
- **url** (str) - Required - The URL of the Git repository.
- **branch_tag** (str) - Required - The name of the branch or tag to clone.
- **config** (autodoc2.config.Config) - Required - The configuration object for autodoc2.

### Request Body
None

### Response
#### Success Response (200)
- **return_value** (pathlib.Path | None) - The path to the cloned repository, or None if cloning failed.

#### Response Example
{
  "return_value": "/path/to/cloned/repo"
}
```

--------------------------------

### RabbitmqManagementClient Initialization (Python)

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.manage.rst

This snippet shows the constructor for the RabbitmqManagementClient class, used for managing RabbitMQ instances. It requires connection details such as username, password, hostname, and virtual host to establish a connection. This client is likely part of the AiiDA system for handling message queuing.

```python
class RabbitmqManagementClient:
    def __init__(self, username: str, password: str, hostname: str, virtual_host: str):
        # ... implementation ...
        pass

```

--------------------------------

### Sandbox Repository Backend

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.repository.rst

Documentation for the SandboxRepositoryBackend class, including its initialization and properties.

```APIDOC
## SandboxRepositoryBackend

### Description
Represents a sandbox repository backend.

### Initialization
#### `__init__(filepath: str | None = None)`
Initializes the SandboxRepositoryBackend.

### Methods
#### `__str__() -> str`
Returns a string representation of the backend.

#### `__del__()`
Cleans up resources when the backend is deleted.

#### `initialise(**kwargs) -> None`
Initialises the sandbox repository.

### Properties
#### `uuid`
- **Type**: `str | None`
- **Description**: The UUID of the repository.

#### `key_format`
- **Type**: `str | None`
- **Description**: The key format used by the repository.

#### `is_initialised`
- **Type**: `bool`
- **Description**: Indicates whether the repository has been initialised.
```

--------------------------------

### XyData Class

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.orm.rst

Represents data with X and Y arrays, suitable for storing tabular data. It provides methods to set and get X and Y data, along with their names and units.

```APIDOC
## XyData Class

### Description
Represents data with X and Y arrays, suitable for storing tabular data. It provides methods to set and get X and Y data, along with their names and units.

### Class
`aiida.orm.nodes.data.array.xy.XyData`

### Methods
- `_arrayandname_validator(array, name, units)` (staticmethod): Validates array, name, and units.
- `set_x(x_array, x_name, x_units)`: Sets the X data.
- `set_y(y_arrays, y_names, y_units)`: Sets the Y data.
- `get_x()`: Retrieves the X data.
- `get_y()`: Retrieves the Y data.
```

--------------------------------

### Process Class Methods

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.engine.rst

This section details the class methods available for the AIIDA Process class, including defining specifications, getting builders, and managing database records.

```APIDOC
## Process Class Methods

### Description
Provides access to class methods for interacting with AIIDA processes, such as defining specifications, retrieving builders, and managing database records.

### Methods

#### `spec()`
- **Description**: Returns the process specification.
- **Method**: CLASSMETHOD
- **Endpoint**: N/A (Class Method)

#### `define(spec: aiida.engine.processes.process_spec.ProcessSpec) -> None`
- **Description**: Defines the process specification.
- **Method**: CLASSMETHOD
- **Endpoint**: N/A (Class Method)

#### `get_builder() -> aiida.engine.processes.builder.ProcessBuilder`
- **Description**: Retrieves the process builder.
- **Method**: CLASSMETHOD
- **Endpoint**: N/A (Class Method)

#### `get_or_create_db_record() -> aiida.orm.ProcessNode`
- **Description**: Gets or creates the database record for the process.
- **Method**: CLASSMETHOD
- **Endpoint**: N/A (Class Method)

#### `get_exit_statuses(exit_code_labels: typing.Iterable[str]) -> typing.List[int]`
- **Description**: Retrieves exit statuses for given exit code labels.
- **Method**: CLASSMETHOD
- **Endpoint**: N/A (Class Method)

#### `exit_codes() -> aiida.engine.processes.exit_code.ExitCodesNamespace`
- **Description**: Returns the namespace for exit codes.
- **Method**: CLASSMETHOD
- **Endpoint**: N/A (Class Method)

```

--------------------------------

### DiskObjectStoreRepositoryBackend Methods

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.repository.rst

This section details the methods available for interacting with the DiskObjectStoreRepositoryBackend.

```APIDOC
## POST /repository/backend/disk_object_store/DiskObjectStoreRepositoryBackend

### Description
Provides methods for managing objects in a disk-based object store repository.

### Method
POST

### Endpoint
/repository/backend/disk_object_store/DiskObjectStoreRepositoryBackend

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "No request body needed for this conceptual endpoint."
}
```

### Response
#### Success Response (200)
Details about the methods available for the DiskObjectStoreRepositoryBackend.

#### Response Example
```json
{
  "methods": [
    "iter_object_streams",
    "delete_objects",
    "list_objects",
    "get_object_hash",
    "maintain",
    "get_info"
  ]
}
```
```

```APIDOC
## POST /repository/backend/disk_object_store/DiskObjectStoreRepositoryBackend/iter_object_streams

### Description
Iterates over object streams in the repository.

### Method
POST

### Endpoint
/repository/backend/disk_object_store/DiskObjectStoreRepositoryBackend/iter_object_streams

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **keys** (List[str]) - Required - A list of keys for the objects to iterate over.

### Request Example
```json
{
  "keys": ["object1.txt", "object2.dat"]
}
```

### Response
#### Success Response (200)
An iterator yielding tuples of object keys and their binary file-like objects.

#### Response Example
```json
{
  "example": "Iterator yielding tuples of (str, BinaryIO)"
}
```
```

```APIDOC
## POST /repository/backend/disk_object_store/DiskObjectStoreRepositoryBackend/delete_objects

### Description
Deletes objects from the repository.

### Method
POST

### Endpoint
/repository/backend/disk_object_store/DiskObjectStoreRepositoryBackend/delete_objects

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **keys** (List[str]) - Required - A list of keys for the objects to delete.

### Request Example
```json
{
  "keys": ["object_to_delete.txt", "another_object.dat"]
}
```

### Response
#### Success Response (200)
Indicates successful deletion. No content is typically returned.

#### Response Example
```json
{
  "message": "Objects deleted successfully."
}
```
```

```APIDOC
## GET /repository/backend/disk_object_store/DiskObjectStoreRepositoryBackend/list_objects

### Description
Lists all objects currently stored in the repository.

### Method
GET

### Endpoint
/repository/backend/disk_object_store/DiskObjectStoreRepositoryBackend/list_objects

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "No request body needed."
}
```

### Response
#### Success Response (200)
An iterable containing the keys (names) of all objects in the repository.

#### Response Example
```json
{
  "object_keys": ["file1.txt", "data.csv", "image.png"]
}
```
```

```APIDOC
## GET /repository/backend/disk_object_store/DiskObjectStoreRepositoryBackend/get_object_hash

### Description
Retrieves the hash of a specific object in the repository.

### Method
GET

### Endpoint
/repository/backend/disk_object_store/DiskObjectStoreRepositoryBackend/get_object_hash

### Parameters
#### Path Parameters
None

#### Query Parameters
- **key** (str) - Required - The key (name) of the object for which to get the hash.

#### Request Body
None

### Request Example
```json
{
  "example": "No request body needed."
}
```

### Response
#### Success Response (200)
The hash of the specified object.

#### Response Example
```json
{
  "key": "my_document.pdf",
  "hash": "a1b2c3d4e5f67890abcdef1234567890"
}
```
```

```APIDOC
## POST /repository/backend/disk_object_store/DiskObjectStoreRepositoryBackend/maintain

### Description
Performs maintenance operations on the repository, such as cleaning up and optimizing storage.

### Method
POST

### Endpoint
/repository/backend/disk_object_store/DiskObjectStoreRepositoryBackend/maintain

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **dry_run** (bool) - Optional - If true, performs a dry run without making changes.
- **live** (bool) - Optional - If true, performs live maintenance operations.
- **pack_loose** (bool) - Optional - Whether to pack loose objects.
- **do_repack** (bool) - Optional - Whether to repack existing archives.
- **clean_storage** (bool) - Optional - Whether to clean up unused storage.
- **do_vacuum** (bool) - Optional - Whether to vacuum the repository.

### Request Example
```json
{
  "dry_run": false,
  "clean_storage": true
}
```

### Response
#### Success Response (200)
A dictionary containing the results of the maintenance operations.

#### Response Example
```json
{
  "status": "completed",
  "space_reclaimed_bytes": 10240,
  "objects_cleaned": 5
}
```
```

```APIDOC
## GET /repository/backend/disk_object_store/DiskObjectStoreRepositoryBackend/get_info

### Description
Retrieves information about the repository's status and usage.

### Method
GET

### Endpoint
/repository/backend/disk_object_store/DiskObjectStoreRepositoryBackend/get_info

### Parameters
#### Path Parameters
None

#### Query Parameters
- **detailed** (bool) - Optional - If true, returns detailed information.

#### Request Body
None

### Request Example
```json
{
  "example": "No request body needed."
}
```

### Response
#### Success Response (200)
A dictionary containing repository information.

#### Response Example
```json
{
  "total_objects": 150,
  "total_size_bytes": 52428800,
  "detailed_info": {
    "storage_type": "disk",
    "available_space_bytes": 1073741824
  }
}
```
```

--------------------------------

### Entry Point Utilities

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.plugins.rst

Functions for managing and loading AIIDA entry points.

```APIDOC
## Entry Point Management

### Description
Utilities for working with AIIDA entry points.

### Functions
- **get_entry_points(group: str) -> importlib_metadata.EntryPoints**
  - **Description**: Retrieves all entry points for a given group.
  - **Parameters**:
    - **group** (str) - Required - The entry point group name.
  - **Response**:
    - **importlib_metadata.EntryPoints** - A collection of entry points.

- **load_entry_point(group: str, name: str) -> typing.Any**
  - **Description**: Loads a specific entry point by group and name.
  - **Parameters**:
    - **group** (str) - Required - The entry point group name.
    - **name** (str) - Required - The name of the entry point.
  - **Response**:
    - **typing.Any** - The loaded entry point object.

- **load_entry_point_from_string(entry_point_string: str) -> typing.Any**
  - **Description**: Loads an entry point from a string representation.
  - **Parameters**:
    - **entry_point_string** (str) - Required - The string representation of the entry point (e.g., 'group.name').
  - **Response**:
    - **typing.Any** - The loaded entry point object.

- **parse_entry_point(group: str, spec: str) -> importlib_metadata.EntryPoint**
  - **Description**: Parses an entry point specification.
  - **Parameters**:
    - **group** (str) - Required - The entry point group name.
    - **spec** (str) - Required - The entry point specification string.
  - **Response**:
    - **importlib_metadata.EntryPoint** - The parsed entry point object.

```

--------------------------------

### Process Instance Methods

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.engine.rst

Details instance methods for the AIIDA Process class, covering initialization, state management, and process control.

```APIDOC
## Process Instance Methods

### Description
Provides access to instance methods for managing and controlling AIIDA processes, including initialization, state saving and loading, and process termination.

### Methods

#### `init() -> None`
- **Description**: Initializes the process.
- **Method**: INSTANCE METHOD
- **Endpoint**: N/A

#### `spec_metadata() -> aiida.engine.processes.ports.PortNamespace`
- **Description**: Returns the metadata for the process specification.
- **Method**: INSTANCE METHOD
- **Endpoint**: N/A

#### `_save_checkpoint() -> None`
- **Description**: Saves the current state of the process as a checkpoint. This is typically an internal method.
- **Method**: INSTANCE METHOD
- **Endpoint**: N/A

#### `save_instance_state(out_state: typing.MutableMapping[str, typing.Any], save_context: typing.Optional[plumpy.persistence.LoadSaveContext]) -> None`
- **Description**: Saves the instance state of the process.
- **Method**: INSTANCE METHOD
- **Endpoint**: N/A

#### `get_provenance_inputs_iterator() -> typing.Iterator[typing.Tuple[str, typing.Union[aiida.engine.processes.ports.InputPort, aiida.engine.processes.ports.PortNamespace]]]`
- **Description**: Returns an iterator for the provenance inputs.
- **Method**: INSTANCE METHOD
- **Endpoint**: N/A

#### `load_instance_state(saved_state: typing.MutableMapping[str, typing.Any], load_context: plumpy.persistence.LoadSaveContext) -> None`
- **Description**: Loads the instance state of the process.
- **Method**: INSTANCE METHOD
- **Endpoint**: N/A

#### `kill(msg: typing.Union[str, None] = None) -> typing.Union[bool, plumpy.futures.Future]`
- **Description**: Kills the process with an optional message.
- **Method**: INSTANCE METHOD
- **Endpoint**: N/A

#### `out(output_port: str, value: typing.Any = None) -> None`
- **Description**: Sets an output value for a given output port.
- **Method**: INSTANCE METHOD
- **Endpoint**: N/A

```

--------------------------------

### Suppress sphinx-autodoc2 warnings in conf.py

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/quickstart.md

Configures Sphinx to suppress warnings emitted by sphinx-autodoc2. This helps in cleaning up build output by hiding known or ignorable warnings.

```python
suppress_warnings = [
    "autodoc2.*",  # suppress all
    "autodoc2.config_error",  # suppress specific
]
```

--------------------------------

### Build Package with Flit

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/README.md

This command uses flit, a tool for building and publishing Python packages, to create a distribution of the project. Flit must be installed via pipx.

```bash
pipx install flit
flit build
```

--------------------------------

### Runner Class Documentation

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.engine.rst

Documentation for the Runner class, including its initialization parameters, context management methods, and properties.

```APIDOC
## Runner Class

### Description
The `Runner` class is responsible for executing processes and managing their lifecycle.

### Initialization

#### `Runner(poll_interval: typing.Union[int, float] = 0, loop: typing.Optional[asyncio.AbstractEventLoop] = None, communicator: typing.Optional[kiwipy.Communicator] = None, rmq_submit: bool = False, persister: typing.Optional[plumpy.persistence.Persister] = None)`
- **Parameters**:
  - `poll_interval` (Union[int, float], optional): The interval for polling. Defaults to `0`.
  - `loop` (Optional[asyncio.AbstractEventLoop], optional): The event loop to use. Defaults to `None`.
  - `communicator` (Optional[kiwipy.Communicator], optional): The communicator instance. Defaults to `None`.
  - `rmq_submit` (bool, optional): Whether to submit via RMQ. Defaults to `False`.
  - `persister` (Optional[plumpy.persistence.Persister], optional): The persister instance. Defaults to `None`.

### Attributes

#### `_persister`
- **Type**: `typing.Optional[plumpy.persistence.Persister]`
- **Value**: `None`
- **Description**: Internal persister instance.

#### `_communicator`
- **Type**: `typing.Optional[kiwipy.Communicator]`
- **Value**: `None`
- **Description**: Internal communicator instance.

#### `_controller`
- **Type**: `typing.Optional[plumpy.process_comms.RemoteProcessThreadController]`
- **Value**: `None`
- **Description**: Internal controller for remote process threads.

#### `_closed`
- **Type**: `bool`
- **Value**: `False`
- **Description**: Flag indicating if the runner is closed.

### Methods

#### `__enter__() -> aiida.engine.runners.Runner`
- **Description**: Enters the runtime context related to this object.

#### `__exit__(exc_type, exc_val, exc_tb)`
- **Description**: Exits the runtime context, handling exceptions.

### Properties

#### `loop`
- **Type**: `asyncio.AbstractEventLoop`
- **Description**: The event loop used by the runner.

#### `transport`
- **Type**: `aiida.engine.transports.TransportQueue`
- **Description**: The transport queue for communication.

#### `persister`
- **Type**: `typing.Optional[plumpy.persistence.Persister]`
- **Description**: The persister instance used by the runner.

#### `communicator`
- **Type**: `typing.Optional[kiwipy.Communicator]`
- **Description**: The communicator instance used by the runner.
```

--------------------------------

### Run Tests with Tox

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/README.md

This command uses tox, a Python tool for automating testing, to run all defined test environments. Ensure tox is installed via pipx.

```bash
pipx install tox
tox -av
```

--------------------------------

### Ignore intersphinx warnings using regex in conf.py

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/quickstart.md

Configures Sphinx to ignore 'reference target not found' warnings using regular expressions. This is an alternative to explicitly replacing annotations or bases.

```python
# ignore all warnings from this package
nitpick_ignore_regex = [
    ("py:.*", r"package\..*"),
]
# ignore a specific warning
nitpick_ignore = [
    ("py:class", "package.module.MyClass"),
]
```

--------------------------------

### Computer Configuration and Status

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.orm.rst

Methods for configuring the computer and retrieving its current configuration details.

```APIDOC
## Computer Configuration and Status

### Description
Methods for configuring the computer and retrieving its configuration details.

### Methods

- **configure(**user: typing.Optional[aiida.orm.User] = None, **kwargs: typing.Any)**: Configures the computer, optionally for a specific user and with additional keyword arguments.
- **get_configuration(user: typing.Optional[aiida.orm.User] = None)**: Retrieves the configuration details of the computer, optionally for a specific user.

### Request Example
```python
# Example for configure
auth_info = computer.configure(user=user, hostname='localhost', port=22)

# Example for get_configuration
config_details = computer.get_configuration(user=user)
print(config_details)
```

### Response
- **configure**: Returns an `AuthInfo` object upon successful configuration.
- **get_configuration**: Returns a dictionary containing the computer's configuration details.
```

--------------------------------

### autodoc2-summary Directive Usage Example

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/summary.md

Demonstrates how to use the `autodoc2-summary` directive in reStructuredText to render a summary of specified objects. It shows the use of the `:renderer:` option and how to list objects with custom titles.

```restructuredtext
.. autodoc2-summary::
    :renderer: myst

    aiida.orm.Node
    ~aiida.orm.Dict
    autodoc2.sphinx.docstring._example my example

```

--------------------------------

### aiida.engine.processes.workchains.workchain.WorkChain

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.engine.rst

Comprehensive documentation for the WorkChain class, covering initialization, attributes, properties, and methods.

```APIDOC
## Class: WorkChain

### Description
Represents a work chain process in AIIDA, orchestrating other processes.

### Initialization
- **Parameters**:
  - **inputs** (dict | None) - Optional dictionary of inputs.
  - **logger** (logging.Logger | None) - Optional logger instance.
  - **runner** (aiida.engine.runners.Runner | None) - Optional runner instance.
  - **enable_persistence** (bool) - Whether to enable persistence (default: True).

### Attributes
- **_node_class** (None) - Internal attribute for node class.
- **_spec_class** (None) - Internal attribute for spec class.
- **_STEPPER_STATE** ('stepper_state') - Internal attribute for stepper state.
- **_CONTEXT** ('CONTEXT') - Internal attribute for context.

### Properties
- **node** (aiida.orm.WorkChainNode) - The WorkChain node associated with this instance.
- **ctx** (aiida.common.extendeddicts.AttributeDict) - The context dictionary for the work chain.

### Methods
- **spec() -> aiida.engine.processes.workchains.workchain.WorkChainSpec**
  - Class method to get the specification of the work chain.
- **save_instance_state(out_state, save_context)**
  - Saves the instance state of the work chain.
- **load_instance_state(saved_state, load_context)**
  - Loads the instance state of the work chain.
- **on_run()**
  - Hook method called when the work chain is run.
- **_resolve_nested_context(key: str) -> tuple[aiida.common.extendeddicts.AttributeDict, str]**
  - Resolves a nested context key.
- **_insert_awaitable(awaitable: aiida.engine.processes.workchains.awaitable.Awaitable) -> None**
  - Inserts an awaitable into the work chain.
- **_resolve_awaitable(awaitable: aiida.engine.processes.workchains.awaitable.Awaitable, value: typing.Any) -> None**
  - Resolves an awaitable with a given value.
- **to_context(**kwargs: aiida.engine.processes.workchains.awaitable.Awaitable | aiida.orm.ProcessNode) -> None**
  - Adds items to the work chain context.
- **_update_process_status() -> None**
  - Updates the process status.
- **run() -> typing.Any**
  - Executes the work chain.
```

--------------------------------

### aiida.engine.processes.ports.WithSerialize

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.engine.rst

Documentation for the WithSerialize class, including its initialization and serialize method.

```APIDOC
## Class: WithSerialize

### Description
Handles serialization of data within AIIDA processes.

### Initialization
Initializes the WithSerialize class.

### Method: serialize
- **Parameters**:
  - **value** (typing.Any) - The value to serialize.
- **Returns**: aiida.orm.Data - The serialized data.
```

--------------------------------

### Setting Default Markdown Rendering with autodoc2_render_plugin

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/quickstart.md

This configuration option in `conf.py` sets the default rendering plugin to 'myst', causing all generated files to use the '.md' extension and interpret docstrings as MyST Markdown by default.

```python
autodoc2_render_plugin = "myst"

```

--------------------------------

### Persistence Utilities

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.engine.rst

Utilities for loading objects from persistence.

```APIDOC
## Persistence Utilities

### Description
Provides documentation for utilities related to loading objects from AIIDA's persistence layer.

### Functions

#### `get_object_loader`

##### Description
Retrieves an object loader instance for accessing persisted AIIDA objects.

##### Method
`get_object_loader`

##### Endpoint
N/A (Python function)
```

--------------------------------

### autodoc2-docstring Directive for MyST Markdown

Source: https://context7.com/sphinx-extensions2/sphinx-autodoc2/llms.txt

Shows how to use the `autodoc2-docstring` directive in MyST Markdown files to embed only the docstring of a Python object. Examples cover literal rendering with syntax highlighting and parsing docstrings with specific parsers.

```markdown
<!-- In MyST Markdown files -->

```{autodoc2-docstring} mypackage.MyClass.my_method
:literal:
:literal-linenos:
:literal-lexer: python
```

<!-- Parsed docstring with specific parser -->
```{autodoc2-docstring} mypackage.utils.helper_function
:parser: myst
:allowtitles:
```

--------------------------------

### Context and Ports

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.engine.rst

Documentation for context management and port handling in AIIDA processes.

```APIDOC
## Context and Ports

### Description
Documentation for context management and port handling in AIIDA processes.

### Data

- **ToContext** (aiida.engine.processes.workchains.context.ToContext): A value used for context management in workchains.

### Classes

- **WithNonDb(*args, **kwargs)**: A class used for handling non-database related process ports.
  ### Initialization
  .. autodoc2-docstring:: aiida.engine.processes.ports.WithNonDb.__init__

  ### Properties
  - **non_db_explicitly_set** (bool) - Flag indicating if non-db was explicitly set.
  - **non_db** - The non-db value.
```

--------------------------------

### autodoc2-docstring Directive for RST

Source: https://context7.com/sphinx-extensions2/sphinx-autodoc2/llms.txt

Explains the `autodoc2-docstring` directive in reStructuredText (RST) for rendering only the docstring of a Python object. It provides examples for literal block rendering with syntax highlighting and line numbers, as well as parsed docstring content.

```restructuredtext
.. Render docstring as literal block with syntax highlighting
.. autodoc2-docstring:: mypackage.MyClass.my_method
   :literal:
   :literal-linenos:
   :literal-lexer: markdown

.. Render docstring as nested content (parsed)
.. autodoc2-docstring:: mypackage.MyClass.my_method
   :parser: myst
   :allowtitles:
```

--------------------------------

### Utility Functions

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.cmdline.rst

Documentation for various utility functions including decorators and echo utilities.

```APIDOC
## Utility Functions

### Description
Documentation for various utility functions including decorators and echo utilities.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### CalcJobNode Methods

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.orm.rst

Provides documentation for key methods of the CalcJobNode class, including retrieving the retrieved node, scheduler stdout/stderr, and the calculation description.

```APIDOC
## CalcJobNode Methods

### Description
This section details methods available on the `CalcJobNode` class for accessing specific information related to a calculation job.

### Methods

#### `get_retrieved_node()`

##### Description
Retrieves the node associated with the retrieved data of the calculation.

##### Method
GET

##### Endpoint
`/api/calcjobnode/{id}/retrieved_node` (Illustrative endpoint, actual access might be via object methods)

##### Response
- **retrieved_node** (Node) - The node representing the retrieved data.

#### `get_scheduler_stdout()`

##### Description
Retrieves the standard output from the scheduler for this calculation.

##### Method
GET

##### Endpoint
`/api/calcjobnode/{id}/scheduler_stdout` (Illustrative endpoint)

##### Response
- **stdout** (str or bytes) - The standard output content.

#### `get_scheduler_stderr()`

##### Description
Retrieves the standard error from the scheduler for this calculation.

##### Method
GET

##### Endpoint
`/api/calcjobnode/{id}/scheduler_stderr` (Illustrative endpoint)

##### Response
- **stderr** (str or bytes) - The standard error content.

#### `get_description()`

##### Description
Retrieves the description of the calculation.

##### Method
GET

##### Endpoint
`/api/calcjobnode/{id}/description` (Illustrative endpoint)

##### Response
- **description** (str) - The description of the calculation.

### Properties

#### `res`

##### Description
Provides access to the `CalcJobResultManager` for handling calculation results.

##### Method
GET

##### Endpoint
`/api/calcjobnode/{id}/res` (Illustrative endpoint)

##### Response
- **result_manager** (CalcJobResultManager) - An object to manage calculation results.
```

--------------------------------

### WorkChain Methods

Source: https://github.com/sphinx-extensions2/sphinx-autodoc2/blob/main/docs/apidocs/aiida/aiida.engine.rst

Documentation for various methods within the WorkChain class, including step execution, node storage, and event handlers.

```APIDOC
## WorkChain Methods

### Description
Provides documentation for core methods of the `aiida.engine.processes.workchains.workchain.WorkChain` class, such as `run`, `_do_step`, `_store_nodes`, `on_exiting`, `on_wait`, `_action_awaitables`, and `_on_awaitable_finished`.

### Methods

#### `run`

##### Description
Executes a WorkChain process.

##### Method
`run`

##### Endpoint
N/A (Python method)

#### `_do_step`

##### Description
Internal method to perform a single step in the WorkChain execution.

##### Method
`_do_step`

##### Endpoint
N/A (Python method)

#### `_store_nodes`

##### Description
Stores nodes associated with the WorkChain execution.

##### Method
`_store_nodes`

##### Endpoint
N/A (Python method)

#### `on_exiting`

##### Description
Callback method executed when the WorkChain is exiting.

##### Method
`on_exiting`

##### Endpoint
N/A (Python method)

#### `on_wait`

##### Description
Callback method executed when the WorkChain is waiting for awaitables to complete.

##### Method
`on_wait`

##### Endpoint
N/A (Python method)

#### `_action_awaitables`

##### Description
Internal method to process awaitable tasks.

##### Method
`_action_awaitables`

##### Endpoint
N/A (Python method)

#### `_on_awaitable_finished`

##### Description
Callback method executed when an awaitable task has finished.

##### Method
`_on_awaitable_finished`

##### Endpoint
N/A (Python method)
```
Tokens:
Raw