Move to pure Asciidoctor for documentation #12611
Conversation
spring-projects-issues
added
the
status: waiting-for-triage
philwebb
added
type: task
|
Instead of copying over the CSS, JS and docinfo files, I'd rather have that as resources in a shared artifact for all Spring projects. Otherwise we'll have to version and maintain those generated files/libraries. |
|
I don't know why I added this to 2.0.x, it should be in the backlog and something we consider for 2.1 |
|
The shared asciidoctor theme has been started, we need to first submit a few PRs there and then publish it as an artifact. |
philwebb
added
the
for: team-attention
bclozel
removed
the
for: team-attention
Per issue-7447, I have removed Docbook from the documet-production tool chain. I also added a collapsible Table of Contents for all the HTML files, changed the styles to match Spring Framework, added an index page for the multi-file HTML version, and fixed a couple of casing issues (significant words starting with lower case in headings) that I saw along the way. A side effect of moving to Asciidoctor was a substantial reduction in the number of HTML files, because we no longer chunk each file. The collapsible ToC makes the larger HTML files more usable, so it should work out well for our readers.
I discovered that we had a .gitignore file that was ignoring HTML and CSS files. That won't work with Asciidoctor, which uses both kinds of files as inputs (not just outputs). I removed the .gitignore file and am adding the necessary HTML and CSS files.
I'm in the middle of making more changes to how Spring Boot's docs get built, and I don't want to lose things, so I'm making an interim commit.
The Asciidoctor Epub3 generator is in Alpha. It is both brittle and missing some features. I had to work around a few things to get reasonable output. Even so, I wound up moving some items in the Epub and the PDF outputs. The information tha was in index-docinfo.xml does not get picked up by the Asciidoctor Epub or PDF generators. I put the author list on the cover and the rest of the information in a file called preamble.adoc, which becomes the first file to be included. That adds one chapter to the Epub and PDF output. I called it legal. It provides the same output as previously for the single-page HTML output.
I was trying to find a better way to re-insert the material we lost by moving to Epub without Asciidoctor (the content of index-docinfo.xml) and forgot to remove the experiment before committing.
While researching how to get the content from index-docinfo.xml into the output, I came across the notion of a colophon, which is a good name for the information in that file. I have consequently changed "Legal" (which I never liked but couldn't think of a better term for at the time) to "Colophon". I also caught that it should be in all outputs, so I removed the conditional check that made it app ly to only the Epub output.
|
I fixed the merge conflict (which I didn't realize I had, or I would have fixed it long ago). Sorry about that. This should be ready for prime time now. |
I made a project for our shared doc resources: https://github.com/spring-projects/spring-doc-resources, so that the whole Spring portfolio would have a single place for the doc resources (so that we can change things like stylesheets in only one place). The changes I made to Spring Boot get the doc resources from that project. |
|
@Buzzardo Thanks! Let me review this PR. I’ll probably send a PR myself to the docs resources project because we need it to generate the css files from the original theme rather than storing them. I’ll let you know if I’ve got questions about it! |
| @@ -960,6 +969,31 @@ | |||
| <profiles> | |||
| <profile> | |||
| <id>full</id> | |||
| <dependencies> | |||
| <dependency> | |||
| <groupId>org.springframework.doc-resources</groupId> | |||
There was a problem hiding this comment.
This is quite an unconventional group id due to the - in it. I would have raised an issue for it in https://github.com/spring-projects/spring-doc-resources but issues appear to be disabled and there's no link to an alternative issue tracker in the README. Could it be changed pleased?
There was a problem hiding this comment.
Should it be org.springframework.doc.resources?
There was a problem hiding this comment.
I think docresources would be more conventional. It would also match other projects like REST Docs (restdocs) and Web Flow (webflow) too.
There’s also a case to be made for it to be io.spring rather than org.springframework. The latter is typically reserved for projects that are used by the community when developing an application, have a programmatic API, etc.
There was a problem hiding this comment.
I'll change it to io.spring.docresources once Brian has finished his review. We have four projects (and growing) that use this set of resources now, so I'll have some changes to make.
|
I've sent a work in progress PR on the doc resources project, see: spring-io/spring-doc-resources#1 I'll update it with stylesheet changes to reflect the Spring Asciidoctor theme, as it's currently just a CSS reset. I'm working with @oodamien on that. |
Remove Guardfile for now; we might reintroduce it later, but it is currently out of sync with the documentation changes. Do not ignore html files in the asciidoc directory as those are needed for docinfo parts. See gh-12611
This commit adds an index page for the multi-file HTML version, and fixed a couple of casing issues (significant words starting with lower case in headings). While researching how to get the content from index-docinfo.xml into the output, I came across the notion of a colophon, which is a good name for the information in that file. I have consequently changed "Legal" (which I never liked but couldn't think of a better term for at the time) to "Colophon". See gh-12611
bclozel
removed
for: merge-with-amendments
Per #7447, I have removed Docbook from the document-production tool chain.
I also added a collapsible Table of Contents for all the HTML files, changed the styles to match Spring Framework, added an index page for the multi-file HTML version, and fixed a couple of casing issues (significant words starting with lower case in headings) that I saw along the way. A side effect of moving to Asciidoctor was a substantial reduction in the number of HTML files, because we no longer chunk each file. The collapsible ToC makes the larger HTML files more usable, so it should work out well for our readers.