Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix broken template processing in jsdoc output #4381

Merged
merged 2 commits into from Aug 18, 2020

Conversation

boneskull
Copy link
Member

@boneskull boneskull commented Jul 22, 2020

because the files generated by jsdoc were output to docs/_site, they were not processed as liquid templates, which meant the custom reporter tutorial was broken (the included "simple reporter" fixture file was not loaded, and the raw template tag was output instead).

to fix this, we needed to:

  1. change the output directory of jsdoc to docs/api (just somewhere else)
  2. add this to .gitignore, obviously
  3. tell eleventy to ignore .gitignore (just rely on its .eleventyignore file)
  4. tell eleventy to pass-through all assets underneath docs/api (css, images, etc)
  5. update the file-loading 11ty data script to output a raw file
  6. update the tutorial to use a fenced code block (jsdoc markdown plugin seems to strip html?) and tell Prettier to ignore the liquid template directive

also:

  • removed link to google group
  • prettier-related reformats
  • tweak data script to use fs.promises

(I lost like 30m on the .gitignore thing. that's surprising behavior on 11ty's part, IMO)

because the files generated by jsdoc were output to `docs/_site`, they were not processed as liquid templates, which meant the custom reporter tutorial was broken.

to fix this, we needed to:

1. change the output directory of jsdoc to `docs/api` (just somewhere else)
2. add this to `.gitignore`, obviously
3. tell eleventy to _ignore_ `.gitignore` (just rely on its `.eleventyignore` file)
4. tell eleventy to pass-through all assets underneath `docs/api` (css, images, etc)
5. update the file-loading 11ty data script to output a raw file
6. update the tutorial to use a fenced code block (jsdoc markdown plugin seems to strip html?) and tell Prettier to ignore the liquid template directive

also:

- removed link to google group
- prettier-related reformats
- tweak data script to use `fs.promises`
@boneskull boneskull added the area: website involving mochajs.org, but not necessarily involving docs label Jul 22, 2020
@boneskull boneskull requested a review from Munter July 22, 2020 22:35
@boneskull boneskull self-assigned this Jul 22, 2020
@boneskull boneskull requested a review from craigtaub July 22, 2020 22:35
@coveralls
Copy link

coveralls commented Jul 22, 2020

Coverage Status

Coverage remained the same at 93.932% when pulling 9b2fb0a on boneskull/fix-custom-reporter-tutorial into 02bdb6b on master.

@boneskull
Copy link
Member Author

Ref: needs mochajs/mocha-docdash#6

@boneskull
Copy link
Member Author

That update to docdash fixes the URLs. 11ty wants to rename all of the files from filename.html to filename/index.html, but jsdoc's links all use filename.html, so all the links were broken (as rightfully caught by the link checker).

The change in docdash should be a major bump since it throws front matter into all of the .html files.

Signed-off-by: Christopher Hiller <boneskull@boneskull.com>
@boneskull boneskull marked this pull request as ready for review July 23, 2020 22:48
@boneskull
Copy link
Member Author

I have some "experimental" changes to the workflow here which:

  1. Avoids re-downloading a bunch of images if the supporters images are already on disk
  2. Does not fail if we cannot download a supporter image
  3. Using npm start docs.dev (renamed from docs.watch--an alias for eleventy --serve), 11ty watches and executes jsdoc when source files change (and avoids this if they do not change, but e.g., docs/index.md does)

I'll open a PR for that stuff after this one lands

@boneskull
Copy link
Member Author

This isn't urgent, so I can wait a bit longer to merge. cc @mochajs/core

Copy link
Contributor

@craigtaub craigtaub left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice one.
I always found docs/api vs docs/_site/api annoying. Didnt even realise https://mochajs.org/api/tutorial-custom-reporter.html existed.

@boneskull boneskull merged commit 24d1dfb into master Aug 18, 2020
@boneskull boneskull deleted the boneskull/fix-custom-reporter-tutorial branch August 18, 2020 18:49
@boneskull boneskull added this to the next milestone Aug 18, 2020
irrationnelle pushed a commit to irrationnelle/mocha that referenced this pull request Aug 23, 2020
because the files generated by jsdoc were output to `docs/_site`, they were not processed as liquid templates, which meant the custom reporter tutorial was broken.

to fix this, we needed to:

1. change the output directory of jsdoc to `docs/api` (just somewhere else)
2. add this to `.gitignore`, obviously
3. tell eleventy to _ignore_ `.gitignore` (just rely on its `.eleventyignore` file)
4. tell eleventy to pass-through all assets underneath `docs/api` (css, images, etc)
5. update the file-loading 11ty data script to output a raw file
6. update the tutorial to use a fenced code block (jsdoc markdown plugin seems to strip html?) and tell Prettier to ignore the liquid template directive

also:

- removed link to google group
- prettier-related reformats
- tweak data script to use `fs.promises`

* update @mocha/docdash

Signed-off-by: Christopher Hiller <boneskull@boneskull.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area: website involving mochajs.org, but not necessarily involving docs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants