Broken link to github source file - missing .

[myosotisgit]

I found Doctum while searching for an auto doc generator with Laravel in mind. I installed and and ran it on our existing app code.
It already picked up comments and made a nice static site. So the doc generator seems to work great. So far so good...

But when i try using the links to the github repo file, it wont work because the link is incorrect. It seems to miss the "." in the url.

Adding a "." before "php" will solve the issue and redirect to Github properly.

In the doctum config i have added the most common values, as mentioned in the Doctum doc sample

Any ideas how to solve the missing . problem ?

[williamdes]

Hi @myosotisgit
Thank you so much for using Doctum and taking time to report this.
May you run tree app command to print out the tree or just take a screenshot or list of files so I can reproduce this issue ?

Reading the code and your description more than twice I am still puzzled about how there could be a mistake in the file path, so let's find out :)

[myosotisgit]

@williamdes
Thank for the swift reply!
We were looking for a simple tool to auto generate documentation and noticed that Laravel is/has using/used your package. We tried it out and it works nicely. So thanks!

We, our programmers, are also stumped and dont know what to do with it. We tried it both on a local dev (windows) and on our test server (ubuntu) thinking it would be a windows/unix issues. But on both instances we get incorrect github links.

I did run a 'tree app' but the output is very large. It goes through all of our app and since it is a laravel/vue app it gets big.
Maybe you were looking for only the Doctum app tree? Not sure what to give you

[williamdes]

Hi @myosotisgit

Would you mind sharing your full config file here in plain text so I can understand how you configured it?

Did you follow the readme example?

[myosotisgit]

Here you go. Straight from the examples

use Doctum\Doctum;
use Doctum\Version\GitVersionCollection;
use Symfony\Component\Finder\Finder;
use Doctum\RemoteRepository\GitHubRemoteRepository;

$dir = 'app';
$iterator = Finder::create()
    ->files()
    ->name('*.php')
    ->in($dir);

// generate documentation for all v2.0.* tags, the 2.0 branch, and the main one
/*$version = GitVersionCollection::create($dir)
    // In a non case-sensitive way, tags containing "PR", "RC", "BETA" and "ALPHA" will be filtered out
    // To change this, use: `$versions->setFilter(static function (string $version): bool { // ... });`
    ->add('master', 'master branch');*/

return new Doctum($iterator, [
    'version'             => 'master',
    'title'                => 'Documentatie Test',
    'language'             => 'en', // Could be 'fr'
    'build_dir'            => __DIR__ . '/../public/doctum/%version%',
    'cache_dir'            => __DIR__ . '/../cache/%version%',
    'source_dir'           => dirname($dir) . '/',
    'remote_repository'    => new GitHubRemoteRepository('myosotisgit/webraap5', dirname($dir)),
    'default_opened_level' => 2, // optional, 2 is the default value
]);

PS
The repository is private btw

[williamdes]

Hi @myosotisgit

I did not manage to reproduce this issue on my side, may you try to change $dir = 'app'; to one particular folder of your app so we can see if with just one folder you can reproduce this issue ?

Sorry for the big delay in my response time

[twouda]

Hi @myosotisgit

I did not manage to reproduce this issue on my side, may you try to change $dir = 'app'; to one particular folder of your app so we can see if with just one folder you can reproduce this issue ?

Sorry for the big delay in my response time

Hi @williamdes
I am a @myosotisgit co-worker and had a look at this.

I changed the config to $dir = 'app/Logging'; A folder which contains a single class and generated the documentation files.

The following link was generated in the Doctum files:

{github_link}/blob/master/Logging/{class}.php#L20

This means the .php extension functions properly, but the 'app' folder is missing.
The correct github link would be:

{github_link}/blob/master/app/Logging/{class}.php#L20

I tried playing around with the config, but did not manage to produce an 'app' folder in the Github link.

Are we missing something in the config maybe?

[williamdes]

Hi @twouda

Are we missing something in the config maybe?

I think there is maybe something specific that needs a full path from the start
You could maybe try to follow this example and let me know: https://github.com/code-lts/doctum/blob/main/tests/phar/data/doctum-absolute.conf.php

[williamdes]

Do you have some news about this one ?

[MichalPniak]

@williamdes I ran into this problem today. I can confirm that the $dir variable must be an absolute path.

// Missing `.`
$dir = 'app';

// Good
$dir = __DIR__.'/app';

[williamdes]

@MichalPniak because you are using a phar, right ?

[MichalPniak]

@williamdes yes