apache / apache/grails-core

[Grails 3] local images defined in 'docs' are not resolved

Open
#9,808 1 comment 0 reactions 0 assignees View on GitHub
info: workaround available type: docs type: minor
Dominant language
Groovy
Stars
2.9k
Forks
975
Avg merge
1d 22h
Merged PRs (30d)
92

Description

After migration to Grails 3 our Project Documentation generated using `docs` command has all local images references broken.

Steps done for demo project:
- Add grails-doc plugin to build: `apply plugin: "org.grails.grails-doc"`
- Add `application.groovy` file with `grails.doc.images = new File("src/docs/images")` option
- create `src/docs/images` and `src/docs/guide` folders
- add image to images
- add toc.yml to guide `page: Page`
- page.gdoc to guide `Image should be displayed !gr8confeu2016.png!`
- execute `gradle docs`

Documentation generated under `build/docs/manual` will look like:
![image](https://cloud.githubusercontent.com/assets/3313302/13917131/3d570f4e-ef5f-11e5-9e55-de91584ef1ef.png)
Link to the image will be `src="../img/gr8confeu2016.png"`

But manual/img folder contains only following files:
![image](https://cloud.githubusercontent.com/assets/3313302/13917162/658e6192-ef5f-11e5-840b-8b3ee498b4ba.png)

Here is an example project with single page and image:
https://github.com/droggo/DocImagesIssue

Contributor guide

Open the contributing guide

Research direction

Reproduce the issue in the linked DocImagesIssue project by running `gradle docs` with the `src/docs/images` and `src/docs/guide` inputs described here. Compare the generated `build/docs/manual/img` contents with the image referenced by `page.gdoc`; done means local images are copied or resolved so the generated manual displays them.

Written by the indexing model from the issue text.

Assessment

Tech stack
groovy
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.