search

yiisoft / yii2-apidoc

Yii 2 apidoc extension.
https://www.yiiframework.com
BSD 3-Clause "New" or "Revised" License
258 stars 121 forks source link

Files/Classes missing in the documentation #277

Closed neoacevedo closed 2 years ago

neoacevedo commented 2 years ago

This issue is related to https://github.com/yiisoft/yii2-apidoc/issues/162

I'm using yii2-apidoc to generate the API documentation for a Laravel project. All classes except only one are well documented.

Under my project structure app\Http\Controllers\Api I have 4 classes under this namespace:

Just this last one, DriverController, is missing from the documentation. The other namespaces are well rendered in the final documentation.

samdark commented 2 years ago

In order to fix it we need it reproduceable so we need a set of files and steps to re-create your situation. Would you please provide these?

neoacevedo commented 2 years ago

What steps will reproduce the problem?

Additional info

Running the command, I get the error: Parse Error: Syntax error, unexpected ')' on line 4801FUNCTION on line 12 Q A
Yii version 2.0.44
Yii APIDoc version 2.1.6
PHP version ~7.4/8.0
Operating system Windows 11/ openSUSE TW
samdark commented 2 years ago

We don't have your Laravel project so can't reproduce it.

neoacevedo commented 2 years ago

Because is a private project, I can't share all, but I'm running some tests, and I think I have found the issue. In the class Api\DriverController, I use in a method the notifiable method to send some notifications for the web users and, if I drop or comment the line using it, the method documentation is rendered, not else if I let the notification method uncommented:

...
                $users = Admin::all();
                foreach ($users as $user) {
                    $user->notifyNow(new WebNotification(
                        ucwords($driver->first_name . " " . $driver->last_name),
                        $driver->picture,
                        $driver->phone,
                        $driver->car_number,
                    ));
                }
...
samdark commented 2 years ago

I'm afraid that's not enough. We need a set of files (it could be not your private project but the same case you've put together) that we can reproduce the issue with.

arogachev commented 2 years ago

Also I recommend to try the latest version of yii2-apidoc (3.0.0).

samdark commented 2 years ago

Yes, trying 3.0.0 definitely worth it. @arogachev did a great job squashing very significant amount of bugs.

neoacevedo commented 2 years ago

app.zip

Updating yii2-apidoc to version 3.0 and trying to generate the documentation raises the error The Yii Framework 2.0 does not seem to be installed. Try running composer install..

Update: The version 3.0 works although I had to copy whole Lavavel rpoject in the yii2 basic project folder to generate the documentation. Before to update yii2-apidoc, I only needed to set the source path where the Laravel project folder, outside the yii2 basic project folder.

samdark commented 2 years ago

Good. So the bug in question is fixed.

Now, additional issue about source path:

  1. What were your paths previously?
  2. What did you execute and from which directory previously?
neoacevedo commented 2 years ago

The yii2 basic app project is under my public_html in the Linux server (Network drive for my windows machine):

For laravel documentation I run inside my-laravel-project: php Z:\yii2-basic-app\vendor\bin\apidoc api . C:\Users\User\Documents\laravel\apidoc --interactive=0 --exclude="vendor" --page-title="Laravel - Documentation". For yii2-basic-app I run php .\vendor\bin\apidoc api . C:\Users\User\Documents\yii2\apidoc --interactive=0 --exclude="vendor" --page-title="Yii2 - Documentation".

My question is, once updated, these commands stopped to work in my Windows PC, not else in my Linux machine. I executed in Windows the composer update command to update all packages for my yii2 basic app waiting it solved the issue but I didn't get any success result.

samdark commented 2 years ago

@arogachev would you please take a look at this paths issue?

arogachev commented 2 years ago

Unfortunately, I can not reproduce this problem. Successfully generated API docs for your app only.

I created test repository for this issue - https://github.com/arogachev/yii2-apidoc-issue-277. What else should be adjusted to better reflect your case (except title, etc.)?

neoacevedo commented 2 years ago

I will post first my current result, I will be after to use your docker and I will post later the results.

My current result with yii2-apidoc at 3.0.1, running public_html as a network drive:

PS X:\yii2-app-basic> php .\vendor\bin\apidoc api . C:\Users\User\Documents\yii2\apidoc --interactive=0 --exclude="vendor" --page-title="Yii2 - Documentación" 

The Yii Framework 2.0 does not seem to be installed. Try running composer install.

The command from linux server:

localhost:~/public_html/yii2-app-basic> php vendor/bin/apidoc api . apidoc --interactive=0 --exclude="vendor" --page-title="Yii2 - Documentación"
Searching files to process... done.
Loading apidoc data from cache... no data available.
Checking for updated files... done.
96 files to update.
Processing files... done.(96/96) ETA: n/a   
Updating cross references and backlinks... done.
Rendering files: done.(97/97) ETA: 192 sec.   
generating extension index files...done.
generating search index...done.
480 errors have been logged to apidoc/errors.txt
98 warnings have been logged to apidoc/warnings.txt
arogachev commented 2 years ago

If I understood correctly, the last error only occurs on Windows OS, right? Maybe something related to network drive... :thinking:

Just in case, I updated the test repo to use "yii2-app-basic" and again, API docs were successfully generated. But I ran tests only on Linux, unfortunately, I can't test it on Windows right now.

Maybe I'm still missing something. A little bit more details about folder / file structure and setup on Windows would be useful.

neoacevedo commented 2 years ago

I have checked and, if I have yii2-apidoc in any Windows directory, I'm able to make the Api Documentation of any of my projects in the network drive, but if I try to run yii2-apidoc from a network drive, I get the mentioned error.

As I said, my projects are located in a Linux PC, and the folder where these are located is mapped in Windows as network drive, for instance, Z:, if I try to run yii2-apidoc from the Z: drive, I get the error while if I run yii2-apidoc from C: or D: (my Windows drives) it runs without problems.

samdark commented 2 years ago

@neoacevedo that looks like a very special edge case that is hard to reproduce. I'm closing the issue but if you'll find out what's wrong exectly, please submit a new one. Thanks.