How to Use the Command 'doctum' (with Examples)

Doctum is a powerful tool designed for automatically generating documentation for PHP APIs. It is a PHP API documentation generator akin to phpDocumentor and Apigen. Using Doctum ensures that your PHP project’s documentation is up-to-date, comprehensive, and easy to understand. This tool is especially useful for developers who want to maintain well-documented codebases that can be easily understood by themselves and others.

Use case 1: Parsing a Project

Code:

doctum parse

Motivation:

Parsing a project is the first step necessary for generating documentation. This process involves analyzing the PHP code to gather all necessary information such as classes, functions, methods, and their relationships within the codebase. Executing doctum parse helps in setting up the initial structure of the documentation without actually rendering it, allowing developers to inspect and correct any errors or inconsistencies in their code base prior to the rendering phase.

Explanation:

• doctum: This part of the command invokes the Doctum tool.
• parse: This argument tells Doctum to perform the parsing operation, which prepares the project’s data structures for documentation.

Example Output:

After running this command, Doctum will initiate the parsing process. It displays progress through the console, indicating the files being parsed and any issues found. You might see something like:

Parsing files...
File processed: src/ExampleClass.php
File processed: src/AnotherClass.php
Parsing completed successfully.

Use case 2: Rendering a Project

Code:

doctum render

Motivation:

After parsing, the next critical step in generating usable documentation is rendering. By executing doctum render, you convert the parsed data into static, visual documentation—often HTML—that can be published to any web server. This step is crucial for making information accessible to all stakeholders, including developers, testers, or even clients, who need to interact with the API documentation in an easy-to-navigate format.

Explanation:

• doctum: The command-line tool being utilized.
• render: This argument specifies that the parsed information should be converted into an output format, typically HTML.

Example Output:

After executing this command, you may see console output reflecting the creation of documentation files:

Rendering documentation...
Creating file: docs/index.html
Creating file: docs/classes/ExampleClass.html
Rendering completed successfully.

Use case 3: Parsing and Rendering a Project

Code:

doctum update

Motivation:

Combining parsing and rendering into a single step can save time and is often more efficient. This one-step command is useful in continuous integration workflows where the goal is to automatically update and render documentation whenever the codebase changes. By doing so, it minimizes manual intervention and ensures that documentation is consistently kept up-to-date with the latest code.

Explanation:

• doctum: The tool for generating documentation.
• update: This action combines both parsing and rendering. Essentially, it tells Doctum to first parse the project and then immediately proceed to render the documentation.

Example Output:

Running this command provides an integrated output, detailing both parsing and rendering process:

Updating documentation...
Parsing files...
File processed: src/ExampleClass.php
Rendering documentation...
Creating file: docs/index.html
Update completed successfully.

Use case 4: Parsing and Rendering Only a Specific Version of a Project

Code:

doctum update --only-version=version

Motivation:

In projects where multiple versions of the codebase are maintained, such as with versioned APIs, it’s often necessary to generate documentation only for a particular version. This command enables maintaining and updating version-specific documentation, which is crucial for projects with backward compatibility requirements or for providing documentation for a stable release while other versions are still in development.

Explanation:

• doctum: The command-line tool for API documentation.
• update: Instructs Doctum to parse and render the project.
• --only-version=version: This option restricts operations to only the specified version of the project. Replace version with the desired version number or identifier.

Example Output:

Executing this command focuses processing on a specific version, shown in console messages:

Updating documentation for version 1.0...
Parsing files for version 1.0...
Rendering version 1.0 documentation...
Creating file: docs/v1.0/index.html
Version-specific update completed successfully.

Use case 5: Parsing and Rendering a Project Using a Specific Configuration

Code:

doctum update path/to/config.php

Motivation:

Complex projects often require configurations that dictate specific rules for generating documentation. By specifying a configuration file, developers can customize the documentation process—such as which directories to include, settings for external dependencies, or custom templates—ensuring the documentation meets their project’s specific needs.

Explanation:

• doctum: The tool for generating API documentation.
• update: This command directs Doctum to first parse and then render the project.
• path/to/config.php: This path points to a PHP configuration file that contains specific settings Doctum should use when processing the project. The configuration file can define settings such as directories to scan, file extensions, namespaces, and more.

Example Output:

Upon running this, it reflects the use of a custom configuration:

Loading configuration from path/to/config.php...
Parsing files according to custom configuration...
Rendering documentation with specified settings...
Documentation update completed using path/to/config.php.

Conclusion:

The Doctum tool offers flexible commands for generating up-to-date, professional PHP API documentation. Whether you need to parse, render, or manage documentation in a more sophisticated, version-controlled manner, Doctum provides the tools to keep your project well-documented and accessible. By integrating these commands into your development workflow, you ensure consistent and helpful documentation for all users and contributors.