From 52033990bd8941d0c37b3b4b371ed19ca8b36e41 Mon Sep 17 00:00:00 2001 From: Ben Schmidt Date: Tue, 29 Sep 2020 20:50:38 +1000 Subject: [PATCH] Minor fixes/improvements to developer documentation. --- CONTRIBUTING.md | 12 +++++++++--- docs/README.md | 6 +++++- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f577479..cc08bba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,7 @@ pdfkit is organized in the following folders: - `docs`: Code and artifacts to generate documentation. - `demo`: Node and browser demos. - `tests/unit`: Tests behavior of specific classes / methods. -- `tests/integration`: Compare the pdf output against a reference. +- `tests/visual`: Compare the pdf output against a reference. **Working on your first Pull Request?** You can learn how from this _free_ series [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github) @@ -64,17 +64,22 @@ Tests are run using [Jest](http://jestjs.io/) and are categorized as unit and vi Visual tests check the pdf image screenshot against a reference stored as snapshots. -Unit tests checks behavior os specific classes / methods isolatedly. +Unit tests check behavior of specific classes / methods isolatedly. -Tests commands +Test commands * `npm run test`: Run all tests * `npm run test:unit`: Run unit tests * `npm run test:visual`: Run visual tests +* `npm run lint`: Run linter To write new tests, look for the *.spec.js files at `test/unit` and `test/visual` as examples > Visual tests should use an embedded font, instead of system fonts, to ensure uniform rendering between different environments +## Documentation + +See `README.md` in the `docs` subdirectory for more information. + ## Submitting a Pull Request Please go through existing issues and pull requests to check if somebody else is already working on it. @@ -82,5 +87,6 @@ Please go through existing issues and pull requests to check if somebody else is Also, make sure to run the tests and lint the code before you commit your changes. > Tests should be added to check the changed behavior even if is a bug fix. + If the proposed change affects document structure a unit test should be added, if affects rendering, add a visual test diff --git a/docs/README.md b/docs/README.md index 77f723b..75bf7f9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,7 +4,11 @@ The PDFKit guide can be read a number of ways. The first is online at [pdfkit.o You can also read the guide in PDF form, in this directory or [online](http://pdfkit.org/docs/guide.pdf). Both the website and the PDF guide are generated from the Markdown files -in this directory. The examples are actually run when generating the PDF in order to show the results inline. +in this directory. Just run `npm run docs` to generate them. +You will need to have ImageMagick 7 installed so the `magick` command is +on your `$PATH`. + +The examples are actually run when generating the PDF in order to show the results inline. The `generate.js` file in this directory is actually quite short. It parses the markdown files into a tree structure using [markdown-js](https://github.com/evilstreak/markdown-js), syntax highlights the code examples using [codemirror](https://github.com/marijnh/codemirror), compiles and runs the code examples and puts the results