Confusing warning "phpDocumentor supports 1 set of API documentation at the moment"

[tadhgboyle]

Seems to be added here: #3477, but without specifics about what exactly will cause this.

I have tried to go through the code and see what causes this exact error, but I can't identify anything.

We are running PHPDocumentor from a Dockerfile, with no extra config and it has been working perfectly until last week:

FROM phpdoc/phpdoc as doc_builder

COPY . /source

RUN mkdir /target && \
    phpdoc -d /source/core/classes \
        -d /source/modules/Core/classes \
        -d "/source/modules/Discord Integration/classes" \
        -d "/source/modules/Cookie Consent/classes" \
        -d /source/modules/Forum/classes \
        -d /source/modules/Members/classes -t /target -i /vendor

FROM nginxinc/nginx-unprivileged:stable

COPY --from=doc_builder /target /usr/share/nginx/html

What are we doing wrong?

[mvriel]

That is a really good question! When you use the command-line like you did, it should create a single set of API Documentation with these settings.

It sounds like there is a bug there, though it probably also meant that you might have been missing some pieces of doc because this error only describes the existing assumptions in the application.. unless the error itself has a bug..

I'll check it out

[mvriel]

I think I found the cause, but I need to verify this in the code yet.

If I remember correctly, there is a slight assumption in phpDocumentor that when you pass absolute paths as source directories, then it will assume they are not part of the same project and thus must be multiple individual Documentation Sets.

I had trouble reproducing your situation until I started using absolute paths like this:

FROM phpdoc/phpdoc as doc_builder

COPY . /source

RUN mkdir /target && \
	phpdoc -d /source/src \
		-d /source/vendor/phpdocumentor \
    	-i /source/vendor/phpdocumentor/flyfinder \
    	-t build/3493

FROM nginxinc/nginx-unprivileged:stable

COPY --from=doc_builder /target /usr/share/nginx/html

If I change that to

FROM phpdoc/phpdoc as doc_builder

COPY . /source

WORKDIR /source

RUN mkdir /target && \
	phpdoc -d src \
		-d vendor/phpdocumentor \
    	-i vendor/phpdocumentor/flyfinder \
    	-t build/3493

FROM nginxinc/nginx-unprivileged:stable

COPY --from=doc_builder /target /usr/share/nginx/html

The issue does not occur.

As such, I recommend using relative paths or a configuration file. What I can do in the mean time is to change the error message and/or documentation to make this clear

[mvriel]

I have just updated the error message with why the error occurs and how it can be resolved: e59fc6e

I apologize for the inconvenience, it would have been handy if we had added this message when we started with the effort to support multiple documentation sets

[tadhgboyle]

Thank you so much 😊