cheezery / depdoc Goto Github PK

View Code? Open in Web Editor NEW

4.0 3.0 5.0 231 KB

Helps you document dependencies of your project

License: MIT License

PHP 99.91% Batchfile 0.09%

depdoc's Introduction

DepDoc helps you document the dependencies of your project, currently supporting Composer and Node packages.

Usage

Creating and updating dependencies file

./vendor/bin/depdoc update

Creates and updates a DEPENDENCIES.md file in your repository, which contains every installed Composer and Node package, its version and description, and offers you a way to document why and how you use this package.

By adding a lock emoji (🔒) after the version number, you can document that this package should not be updated. Alternatively you can use 🛇, ⚠, or ✋.

Validating dependencies file

./vendor/bin/depdoc validate

Validates that every installed dependency is documented in DEPENDENCIES.md. Also makes sure that no package surpasses its locked version.

Use strict modes to verify your package version matches the documented dependencies.

./vendor/bin/depdoc validate --strict

Checks for major and minor version to match, i.e. installed 1.0.1 and documented 1.0.0 will bypass validation but installed 1.1.0 and documented 1.0.0 won't.

./vendor/bin/depdoc validate --very-strict

Checks for full semantic versioning match, i.e. installed 1.0.1 and documented 1.0.0 will not bypass validation.

Configuration

Configuration can be provided via .depdoc.json, .depdoc.yml or .depdoc.yml files in the root directory of your project.

Options

newlineCharacter

Default is \n but if you need a different one you can provide it.

lockSymbol

Default is "🔒". Alternatively you can use 🛇, ⚠, or ✋.

exportExternalLink

Default is true, but if you do not want the external link in your dependencies file you can deactivate it.

composer

Default is true, if you do not want to add composer dependencies set this to false

npm

Default is true, if you do not want to add npm dependencies set this to false.

depdoc's People

Contributors

Stargazers

Watchers

Forkers

t-moennich reinfi godlesz tom-sapletta-com alexdo

depdoc's Issues

Consider adding table of contents

Decide wheter it's a good idea to add table of contents at beginning of DEPENDENCIES.md. If so then include it!

Configure used package managers

Hey folks,

I would like to use DepDoc for one of my projects, but I would only like to document composer packages not the node ones.

For my opinion this should be part of the configuration file.

I.e. for yml

composer: true
npm: true

or

managers:
    composer: true
    npm: true

Default would of course be true.

Evaluate possibility to enhance external links in DEPENDENCIES.md (and implement)

Following #2 evaluate if it's a good idea and if there's a reliable way to enhance external links written to output file. See this discussion for details.

Enhance README file

Document new CLI arguments
Mention possibility to add own stuff underneath each dependency and its description
Add example DEPENDENCIES.md file and link to it in README

Use system aware line break in DEPENDENCIES.md

Improve writing of Markdown file by not just using \r\n to end line.

See MarkdownWriter.php.

PHP Notice: Undefined index: description

18-Sep-2018 10:20:35	PHP Notice:  Undefined index: description in /some/path/vendor/cheezery/depdoc/src/PackageManager/NodePackageManager.php on line 46
18-Sep-2018 10:20:35	PHP Stack trace:
18-Sep-2018 10:20:35	PHP   1. {main}() /some/path/vendor/cheezery/depdoc/bin/depdoc:0
18-Sep-2018 10:20:35	PHP   2. DepDoc\Application\DepDocApplication->run() /some/path/vendor/cheezery/depdoc/bin/depdoc:16
18-Sep-2018 10:20:35	PHP   3. DepDoc\Application\DepDocApplication->doRun() /some/path/vendor/symfony/console/Application.php:145
18-Sep-2018 10:20:35	PHP   4. DepDoc\Application\DepDocApplication->doRunCommand() /some/path/vendor/symfony/console/Application.php:262
18-Sep-2018 10:20:35	PHP   5. DepDoc\Command\UpdateCommand->run() /some/path/vendor/symfony/console/Application.php:886
18-Sep-2018 10:20:35	PHP   6. DepDoc\Command\UpdateCommand->execute() /some/path/vendor/symfony/console/Command/Command.php:251
18-Sep-2018 10:20:35	PHP   7. DepDoc\Command\UpdateCommand->getInstalledPackages() /some/path/vendor/cheezery/depdoc/src/Command/UpdateCommand.php:68
18-Sep-2018 10:20:35	PHP   8. DepDoc\PackageManager\NodePackageManager->getInstalledPackages() /some/path/vendor/cheezery/depdoc/src/Command/BaseCommand.php:77

Referencing zend-framework/service-manager

Hey,

why is there a requirement of the zend-framework/service-manager?

Can not find any usage?

Trim all trailing whitespaces after generating DEPENDENCIES.MD

When there's no description available for a library or when it contains only of whitespace, the resulting Markdown file will contain this whitespace as well. This might lead to unnecessary conflicts, when someone's IDE trims this whitespaces automatically. So depdoc should trim them after generation.

Improve determining Composer package versions

When running depdoc (either validate or update) what's take the longest is determining the installed packages of Composer and npm. Also we do this by executing a CLI command, there should be better ways to do this.

I found Ocramius/PackageVersions which offers a nice utility function to get the installed version of a specific Composer package. Maybe it can be enhanced to get versions of all (directly) required packages.
I also saw that they ingeniously read the installed versions after install or update (see here).
They're also requiring composer/composer directly, which to me seems to be a lot better than running a CLI command and parsing the output (they also require "composer-plugin-api", which might be the actual way to use Composer stuff in your project).
There's also Rinvex Composer which promotes itself as an "intuitive package that utilizes Composer Plugin API".

Add external link to package repository in DEPENDENCIES.md

Next to the name, the installed version, and the description of the package there should be a external link to the repository in the DEPENDENCIES.md.

Strict mode for validate command

Actually the validate command just checks the presence of the packages, i.e. if one is removed or one added but not documented.
It also checks the pinned versions if there installed version matches.

I would like to have a --strict mode for the validate command which then validated all versions to be equal to the one documented.

Any opinions on that?

Add possibility to add own sections in DEPENDENCIES.md

Currently there's no way to add own sections to the markdown, they will be removed everytime you run depoc update. Own sections preceded with ### should stay in DEPENDENCIES.md after an update.

Add possiblity to configure depdoc usage

Options which should be included

Used lock symbol
Toggle description in DEPENDECIES.md
Toggle external link in DEPENDECIES.md (link not yet implemented, see #2)
Exclude package manager
~~Toggle table of contents in MD file (if included, see #4)~~

Decide which config file format to use (should probably be json, yaml, or both).