Skip to content

Commit b230de7

Browse files
PoloStyle07PoloStyle07
committed
- Initial commit for artisan-docs generation
0 parents  commit b230de7

21 files changed

Lines changed: 10750 additions & 0 deletions

‎.gitignore‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
/vendor/
2+
node_modules/
3+
npm-debug.log
4+
yarn-error.log
5+
6+
# Laravel 4 specific
7+
bootstrap/compiled.php
8+
app/storage/
9+
10+
# Laravel 5 & Lumen specific
11+
public/storage
12+
public/hot
13+
14+
# Laravel 5 & Lumen specific with changed public path
15+
public_html/storage
16+
public_html/hot
17+
18+
storage/*.key
19+
.env
20+
Homestead.yaml
21+
Homestead.json
22+
/.vagrant
23+
.phpunit.result.cache
24+
25+
/public/build
26+
/storage/pail
27+
.env.backup
28+
.env.production
29+
.phpactor.json
30+
auth.json

‎CONTRIBUTING.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Contributing
2+
3+
Thank you for considering contributing to **artisan-docs**! Whether you're reporting a bug, suggesting a feature, or submitting a pull request, your help is greatly appreciated.
4+
5+
---
6+
7+
## Reporting Bugs
8+
9+
If you've found a bug, please [open an issue](https://github.com/codeinstinctai/artisan-docs/issues/new) and include the following:
10+
11+
- A **clear and descriptive title**.
12+
- The **Laravel and PHP versions** you are running.
13+
- **Reproducible steps** — the smallest set of actions that consistently trigger the bug.
14+
- The **expected behaviour** and what you observed instead.
15+
- Any relevant **error messages or stack traces**.
16+
17+
The more detail you provide, the faster the issue can be triaged and resolved.
18+
19+
---
20+
21+
## Feature Requests
22+
23+
Have an idea that would make artisan-docs more useful? [Open an issue](https://github.com/codeinstinctai/artisan-docs/issues/new) and:
24+
25+
- Use a **clear and descriptive title** prefixed with `[Feature Request]`.
26+
- Explain the **problem you are trying to solve** and why existing behaviour does not address it.
27+
- Describe the **proposed solution** or API you have in mind.
28+
- If applicable, include **examples** of what the new functionality would look like.
29+
30+
Feature requests are reviewed and discussed openly on the issue tracker before any implementation begins.
31+
32+
---
33+
34+
## Development Setup
35+
36+
To set up a local development environment, clone the repository and install dependencies via Composer:
37+
38+
```bash
39+
git clone https://github.com/codeinstinctai/artisan-docs.git
40+
cd artisan-docs
41+
composer install
42+
```
43+
44+
No additional services or environment variables are required — the package uses [Orchestra Testbench](https://github.com/orchestral/testbench) to bootstrap a Laravel application for testing.
45+
46+
---
47+
48+
## Testing and Linting
49+
50+
Before submitting a pull request, please ensure all tests pass and the code style is consistent.
51+
52+
### Running Tests (PHPUnit)
53+
54+
```bash
55+
composer test
56+
```
57+
58+
This executes the full PHPUnit test suite via `vendor/bin/phpunit`, as defined in the project's `composer.json`.
59+
60+
### Running the Linter (Laravel Pint)
61+
62+
```bash
63+
composer lint
64+
```
65+
66+
This runs Laravel Pint via `vendor/bin/pint` to automatically fix code-style issues according to the project's conventions, as defined in the project's `composer.json`.
67+
68+
Both commands must complete without errors before a pull request will be reviewed.
69+
70+
---
71+
72+
## Pull Request Process
73+
74+
1. **Fork** the repository and create your branch from `main`:
75+
```bash
76+
git checkout -b feature/my-new-feature
77+
```
78+
Use a descriptive branch name that reflects the change (e.g. `fix/html-output-encoding`, `feature/csv-export-format`).
79+
80+
2. **Make your changes**, keeping commits focused and atomic. Write **descriptive commit messages** that explain *why* a change was made, not just *what* changed:
81+
```
82+
Add --namespace flag to scope HTML output to a single group
83+
84+
Previously the --namespace filter only applied to Markdown output.
85+
This change propagates the filter through to the HTML generator so
86+
all three formats behave consistently.
87+
```
88+
89+
3. **Add or update tests** to cover your changes. Pull requests that reduce test coverage are unlikely to be merged.
90+
91+
4. **Run tests and linting** (see above) and confirm everything passes locally.
92+
93+
5. **Open a pull request** against the `main` branch. In the PR description:
94+
- Reference any related issue (e.g. `Closes #42`).
95+
- Summarise *what* changed and *why*.
96+
- Include any notes on backwards compatibility or migration steps.
97+
98+
6. A maintainer will review your pull request. Please be responsive to feedback — PRs that go stale may be closed.
99+
100+
---
101+
102+
Thank you for helping make artisan-docs better! 🎉

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 PoloStyle07
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# artisan-docs
2+
3+
[![Tests](https://github.com/codeinstinctai/artisan-docs/actions/workflows/tests.yml/badge.svg)](https://github.com/codeinstinctai/artisan-docs/actions)
4+
[![Latest Version](https://img.shields.io/packagist/v/code-instinct/artisan-docs.svg)](https://packagist.org/packages/code-instinct/artisan-docs)
5+
[![License](https://img.shields.io/packagist/l/code-instinct/artisan-docs.svg)](LICENSE)
6+
7+
Automatically generate structured reference documentation for **every Artisan command** registered in your Laravel application — including custom commands, third-party packages, and Laravel's own built-in commands.
8+
9+
---
10+
11+
## Installation
12+
13+
```bash
14+
composer require code-instinct/artisan-docs
15+
```
16+
17+
Laravel's auto-discovery will register the service provider automatically.
18+
19+
Optionally publish the config and/or the HTML template:
20+
21+
```bash
22+
# Publish configuration
23+
php artisan vendor:publish --tag=artisan-docs-config
24+
25+
# Publish HTML Blade template (for customisation)
26+
php artisan vendor:publish --tag=artisan-docs-views
27+
```
28+
29+
---
30+
31+
## Usage
32+
33+
### Zero-config (Markdown, outputs to `docs/commands.md`)
34+
```bash
35+
php artisan docs:commands
36+
```
37+
38+
### Choose output format
39+
```bash
40+
php artisan docs:commands --format=html --output=docs/commands.html
41+
php artisan docs:commands --format=json --output=docs/commands.json
42+
php artisan docs:commands --format=markdown --output=README-commands.md
43+
```
44+
45+
### Filtering
46+
```bash
47+
# Only application-defined commands (in App\Console\Commands)
48+
php artisan docs:commands --only-custom
49+
50+
# Exclude anything that lives in vendor/
51+
php artisan docs:commands --exclude-vendor
52+
53+
# Scope to a single namespace
54+
php artisan docs:commands --namespace=make
55+
56+
# Also surface hidden commands
57+
php artisan docs:commands --include-hidden
58+
```
59+
60+
### CI check — fail if docs are out of sync
61+
```bash
62+
php artisan docs:commands --check
63+
```
64+
Exits with code `1` when the committed documentation file does not match the current command structure. Ideal for a CI gate.
65+
66+
---
67+
68+
## Configuration
69+
70+
After publishing, edit `config/artisan-docs.php`:
71+
72+
| Key | Default | Description |
73+
|-----|---------|-------------|
74+
| `default_format` | `markdown` | `markdown`, `html`, or `json` |
75+
| `default_output` | `docs/commands.md` | Output file path (relative to base path) |
76+
| `include_hidden` | `false` | Include hidden commands |
77+
| `include_vendor` | `true` | Include vendor package commands |
78+
| `excluded_namespaces` | `['_', 'completion']` | Namespaces to always skip |
79+
| `excluded_commands` | `[]` | Specific command names to skip |
80+
| `groups` | *(see config)* | Map namespace → group display name |
81+
| `app_command_paths` | `['App\\Console\\Commands\\']` | Paths used to detect custom commands |
82+
| `html_template` | `artisan-docs::commands` | Blade view for HTML output |
83+
| `title` | `Artisan Command Reference` | Document title |
84+
85+
---
86+
87+
## Output Formats
88+
89+
### Markdown
90+
GitHub-friendly tables for arguments and options, TOC with anchor links, group sections.
91+
92+
### HTML
93+
Self-contained, dark-themed single-page reference with a sticky sidebar navigation. Zero external dependencies — ship it to GitHub Pages, an S3 bucket, or your internal wiki.
94+
95+
### JSON
96+
Machine-readable structure for integration with Confluence, Notion, or custom tooling.
97+
98+
---
99+
100+
## Customising the HTML Template
101+
102+
```bash
103+
php artisan vendor:publish --tag=artisan-docs-views
104+
```
105+
106+
Edit `resources/views/vendor/artisan-docs/commands.blade.php`.
107+
Update `html_template` in your config to `artisan-docs::commands` (default already points to it after publishing).
108+
109+
---
110+
111+
## Testing
112+
113+
```bash
114+
composer test
115+
```
116+
117+
## Linting
118+
119+
```bash
120+
composer lint
121+
```
122+
123+
---
124+
125+
## Contributing
126+
127+
Contributions are welcome! If you've found a bug, have a feature request, or want to submit a pull request, please read the [Contributing Guidelines](CONTRIBUTING.md) to get started.
128+
129+
---
130+
131+
## License
132+
133+
Open-sourced software licensed under the [MIT LICENSE](LICENSE).

‎composer.json‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
{
2+
"name": "code-instinct/artisan-docs",
3+
"description": "Automatically generate documentation for all Artisan commands in a Laravel application.",
4+
"keywords": ["laravel", "artisan", "documentation", "commands", "docs"],
5+
"license": "MIT",
6+
"type": "library",
7+
"authors": [
8+
{
9+
"name": "Code Instinct",
10+
"email": "info@codeinstinct.nl"
11+
}
12+
],
13+
"require": {
14+
"php": "^8.1",
15+
"illuminate/console": "^10.0|^11.0|^12.0",
16+
"illuminate/contracts": "^10.0|^11.0|^12.0",
17+
"illuminate/support": "^10.0|^11.0|^12.0"
18+
},
19+
"require-dev": {
20+
"orchestra/testbench": "^8.0|^9.0|^10.0",
21+
"phpunit/phpunit": "^10.0|^11.0",
22+
"laravel/pint": "^1.0"
23+
},
24+
"autoload": {
25+
"psr-4": {
26+
"CodeInstinct\\ArtisanDocs\\": "src/"
27+
}
28+
},
29+
"autoload-dev": {
30+
"psr-4": {
31+
"CodeInstinct\\ArtisanDocs\\Tests\\": "tests/"
32+
}
33+
},
34+
"extra": {
35+
"laravel": {
36+
"providers": [
37+
"CodeInstinct\\ArtisanDocs\\ArtisanDocsServiceProvider"
38+
]
39+
}
40+
},
41+
"scripts": {
42+
"test": "vendor/bin/phpunit",
43+
"lint": "vendor/bin/pint"
44+
},
45+
"config": {
46+
"sort-packages": true
47+
},
48+
"minimum-stability": "stable",
49+
"prefer-stable": true
50+
}

0 commit comments

Comments
 (0)