How to use the command `doctum` (with examples)

The doctum command is a PHP API documentation generator, which helps in parsing and rendering PHP projects to generate API documentation. It is a powerful tool for developers working on PHP projects who want to automate the process of documenting their code.

Use case 1: Parse a project

Code:

doctum parse

Motivation: Parsing a project using the doctum parse command is the first step towards generating API documentation. By running this command, doctum will analyze the PHP files in the specified project and extract information about classes, methods, properties, and more.

Explanation:

• doctum - The command to run the doctum tool.
• parse - The action to parse the project.

Example output:

Parsing project...
Successfully parsed project.

Use case 2: Render a project

Code:

doctum render

Motivation: Rendering a project using the doctum render command is the second step to generate API documentation. After parsing the project, doctum takes the collected information and generates the HTML files for the documentation.

Explanation:

• doctum - The command to run the doctum tool.
• render - The action to render the project.

Example output:

Rendering project...
Successfully rendered project.

Use case 3: Parse then render a project

Code:

doctum update

Motivation: The doctum update command combines the parsing and rendering steps into a single operation. It parses the project to collect the necessary information and then renders the generated documentation in one go.

Explanation:

• doctum - The command to run the doctum tool.
• update - The action to parse and render the project.

Example output:

Parsing project...
Rendering project...
Successfully parsed and rendered project.

Use case 4: Parse and render only a specific version of a project

Code:

doctum update --only-version=version

Motivation: When working on a PHP project with multiple versions, it is helpful to document each version separately. The --only-version argument allows specifying a specific version to parse and render the project, ensuring that only the relevant documentation is generated.

Explanation:

• doctum - The command to run the doctum tool.
• update - The action to parse and render the project.
• --only-version=version - An argument to specify the version to parse and render.

Example output:

Parsing and rendering project for version 1.2.0...
Successfully parsed and rendered project for version 1.2.0.

Use case 5: Parse and render a project using a specific configuration

Code:

doctum update path/to/config.php

Motivation: The doctum tool supports custom configurations. By providing the path to a specific configuration file, the doctum command can parse and render a project using the settings defined in that file.

Explanation:

• doctum - The command to run the doctum tool.
• update - The action to parse and render the project.
• path/to/config.php - An argument that specifies the path to the configuration file.

Example output:

Parsing and rendering project using custom configuration...
Successfully parsed and rendered project with custom configuration.

Conclusion:

The doctum command is a valuable tool for PHP developers to generate API documentation for their projects. By utilizing the various use cases such as parsing, rendering, version-specific documentation, and custom configurations, developers can automate the process of documenting their PHP code.