Affects: 5.x

The directory for the PDF documentation contains HTML files and JS and CSS directories that, AFAIK, don't need to be there and can be a bit confusing. For example, if you're not familiar with Asciidoctor you may open docinfo.html expecting some information about the PDF documentation. You get a blank page instead.

Comment From: sbrannen

Good catch!

We'll clean that up.

Note to self: we also have some included files that erroneously end up as top-level HTML and PDF documents. We might want to create a separate ticket for those, but before I forget... these are the ones I noticed.

  • data-access-appendix.html / data-access-appendix.pdf
  • integration-appendix.html / integration-appendix.pdf
  • testing-webtestclient.html / testing-webtestclient.pdf

Comment From: sbrannen

Examples of what haven been published in the pdf folder for various 5.x releases:

  • https://docs.spring.io/spring/docs/5.0.19.RELEASE/spring-framework-reference/pdf/
  • https://docs.spring.io/spring/docs/5.1.18.RELEASE/spring-framework-reference/pdf/
  • https://docs.spring.io/spring/docs/5.2.9.RELEASE/spring-framework-reference/pdf/ (https://docs.spring.io/spring/docs/current/spring-framework-reference/pdf/)
  • https://docs.spring.io/spring-framework/docs/5.3.0-RC1/reference/pdf/

Comment From: sbrannen

I've revised the scope of this ticket to address the original issue regarding HTML artifacts in the PDF folder as well as the additional, unnecessary top-level documents mentioned in https://github.com/spring-projects/spring-framework/issues/25783#issuecomment-694885011.

Comment From: sbrannen

Related issue regarding the undesired copying of resources to the PDF output folder: https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/569

Comment From: sbrannen

The following are the before and after states of the generated output regarding the unnecessary copying of resources to the pdf folder.

Before

├── html5
│   ├── core.html
│   ├── css
│   │   ├── spring.css
│   │   └── stylesheet.css
│   ├── data-access-appendix.html
│   ├── data-access.html
│   ├── docinfo-footer.html
│   ├── docinfo.html
│   ├── favicon.ico
│   ├── images
│   │   ├── DataAccessException.png
│   │   ├── aop-proxy-call.png
│   │   ├── aop-proxy-plain-pojo-call.png
│   │   ├── container-magic.png
│   │   ├── message-flow-broker-relay.png
│   │   ├── message-flow-simple-broker.png
│   │   ├── mvc-context-hierarchy.png
│   │   ├── oxm-exceptions.png
│   │   ├── prototype.png
│   │   ├── singleton.png
│   │   ├── spring-mvc-and-webflux-venn.png
│   │   ├── tx.png
│   │   ├── tx_prop_required.png
│   │   └── tx_prop_requires_new.png
│   ├── index.html
│   ├── integration-appendix.html
│   ├── integration.html
│   ├── js
│   │   ├── highlight
│   │   │   ├── highlight.min.js
│   │   │   └── styles
│   │   │       ├── atom-one-light.min.css
│   │   │       ├── github-gist.min.css
│   │   │       ├── github.min.css
│   │   │       ├── googlecode.min.css
│   │   │       └── solarized-light.min.css
│   │   ├── toc.js
│   │   └── tocbot
│   │       ├── tocbot.css
│   │       └── tocbot.min.js
│   ├── languages.html
│   ├── overview.html
│   ├── rsocket.html
│   ├── testing-webtestclient.html
│   ├── testing.html
│   ├── web-reactive.html
│   └── web.html
└── pdf
    ├── core.pdf
    ├── css
    │   ├── spring.css
    │   └── stylesheet.css
    ├── data-access-appendix.pdf
    ├── data-access.pdf
    ├── docinfo-footer.html
    ├── docinfo.html
    ├── favicon.ico
    ├── images
    │   ├── DataAccessException.png
    │   ├── aop-proxy-call.png
    │   ├── aop-proxy-plain-pojo-call.png
    │   ├── container-magic.png
    │   ├── message-flow-broker-relay.png
    │   ├── message-flow-simple-broker.png
    │   ├── mvc-context-hierarchy.png
    │   ├── oxm-exceptions.png
    │   ├── prototype.png
    │   ├── singleton.png
    │   ├── spring-mvc-and-webflux-venn.png
    │   ├── tx.png
    │   ├── tx_prop_required.png
    │   └── tx_prop_requires_new.png
    ├── index.pdf
    ├── integration-appendix.pdf
    ├── integration.pdf
    ├── js
    │   ├── highlight
    │   │   ├── highlight.min.js
    │   │   └── styles
    │   │       ├── atom-one-light.min.css
    │   │       ├── github-gist.min.css
    │   │       ├── github.min.css
    │   │       ├── googlecode.min.css
    │   │       └── solarized-light.min.css
    │   ├── toc.js
    │   └── tocbot
    │       ├── tocbot.css
    │       └── tocbot.min.js
    ├── languages.pdf
    ├── overview.pdf
    ├── rsocket.pdf
    ├── testing-webtestclient.pdf
    ├── testing.pdf
    ├── web-reactive.pdf
    └── web.pdf

After

├── html5
│   ├── core.html
│   ├── css
│   │   ├── spring.css
│   │   └── stylesheet.css
│   ├── data-access-appendix.html
│   ├── data-access.html
│   ├── docinfo-footer.html
│   ├── docinfo.html
│   ├── favicon.ico
│   ├── images
│   │   ├── DataAccessException.png
│   │   ├── aop-proxy-call.png
│   │   ├── aop-proxy-plain-pojo-call.png
│   │   ├── container-magic.png
│   │   ├── message-flow-broker-relay.png
│   │   ├── message-flow-simple-broker.png
│   │   ├── mvc-context-hierarchy.png
│   │   ├── oxm-exceptions.png
│   │   ├── prototype.png
│   │   ├── singleton.png
│   │   ├── spring-mvc-and-webflux-venn.png
│   │   ├── tx.png
│   │   ├── tx_prop_required.png
│   │   └── tx_prop_requires_new.png
│   ├── index.html
│   ├── integration-appendix.html
│   ├── integration.html
│   ├── js
│   │   ├── highlight
│   │   │   ├── highlight.min.js
│   │   │   └── styles
│   │   │       ├── atom-one-light.min.css
│   │   │       ├── github-gist.min.css
│   │   │       ├── github.min.css
│   │   │       ├── googlecode.min.css
│   │   │       └── solarized-light.min.css
│   │   ├── toc.js
│   │   └── tocbot
│   │       ├── tocbot.css
│   │       └── tocbot.min.js
│   ├── languages.html
│   ├── overview.html
│   ├── rsocket.html
│   ├── testing-webtestclient.html
│   ├── testing.html
│   ├── web-reactive.html
│   └── web.html
└── pdf
    ├── core.pdf
    ├── data-access-appendix.pdf
    ├── data-access.pdf
    ├── index.pdf
    ├── integration-appendix.pdf
    ├── integration.pdf
    ├── languages.pdf
    ├── overview.pdf
    ├── rsocket.pdf
    ├── testing-webtestclient.pdf
    ├── testing.pdf
    ├── web-reactive.pdf
    └── web.pdf

Comment From: sbrannen

The directory for the PDF documentation contains HTML files and JS and CSS directories that, AFAIK, don't need to be there and can be a bit confusing.

This has been addressed in my most recent commit. If you notice any issues with the generated output after these changes, please let me know.

I'm keeping this issue open to address further issues mentioned in https://github.com/spring-projects/spring-framework/issues/25783#issuecomment-694885011.

Comment From: sbrannen

Reopening to apply fixes in 5.2.x as well.

Comment From: bclozel

Reopening as the reference docs are now missing from the zip archive.

➜  docs wget https://repo.spring.io/snapshot/org/springframework/spring/5.3.0-SNAPSHOT/spring-5.3.0-20200923.191224-393-docs.zip
--2020-09-24 18:05:15--  https://repo.spring.io/snapshot/org/springframework/spring/5.3.0-SNAPSHOT/spring-5.3.0-20200923.191224-393-docs.zip
Resolving repo.spring.io (repo.spring.io)... 35.241.58.96
Connecting to repo.spring.io (repo.spring.io)|35.241.58.96|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 31233368 (30M) [application/zip]
Saving to: ‘spring-5.3.0-20200923.191224-393-docs.zip’

spring-5.3.0-20200923.191224- 100%[=================================================>]  29,79M  23,7MB/s    in 1,3s

2020-09-24 18:05:16 (23,7 MB/s) - ‘spring-5.3.0-20200923.191224-393-docs.zip’ saved [31233368/31233368]

➜  docs tar -xzf spring-5.3.0-20200923.191224-393-docs.zip
➜  docs ls
javadoc-api                               spring-5.3.0-20200923.191224-393-docs.zip
kdoc-api

Comment From: sdeleuze

Thanks @bclozel for fixing this.