Documentation site with docsify #343
Conversation
|
Note that any package level items from the API can be hidden by marking them with "@internal". I may be able to add a feature to api-documenter to additionally not index certain items... |
There was a problem hiding this comment.
Very great job ;)
The generated documentation looks clearly better than the one I generated so far: https://dubzzz.github.io/fast-check/
The only issue in it is maybe the fact that it does not seem to handle the overloads correctly. Negligible compared to the looks and feel ;)
Please add yourself in the https://github.com/dubzzz/fast-check/blob/master/CONTRIBUTORS.md file
Small changes are requested:
- replace the yarn.lock by the package-lock
- docs:2 should replace docs
- small change required in tarvis.yml to make it work with the new doc
- no need for gh-pages for this review
package.json
Outdated
| "@types/jest": "^24.0.11", | ||
| "@types/node": "^11.11.3", | ||
| "benchmark": "^2.1.4", | ||
| "browserify": "^16.2.3", | ||
| "coveralls": "^3.0.3", | ||
| "docsify-tools": "^1.0.8", | ||
| "gh-pages": "^2.0.1", |
There was a problem hiding this comment.
No need for the gh-pages package for the moment. I already handle the deployment of documentation in https://github.com/dubzzz/fast-check/blob/master/.travis.yml#L63:L76
| @@ -50,11 +52,14 @@ | |||
| "pure-rand": "^1.6.2" | |||
| }, | |||
| "devDependencies": { | |||
There was a problem hiding this comment.
Please commit the package-lock.json instead of the yarn.lock. I prefer to only handle one locking system for the moment.
package.json
Outdated
| @@ -31,7 +31,9 @@ | |||
| "format": "prettier --write \"**/*.{js,ts}\"", | |||
| "format:check": "prettier --list-different \"**/*.{js,ts}\"", | |||
| "lint": "tslint --project tsconfig.json --fix", | |||
| "lint:check": "tslint --project tsconfig.json" | |||
| "lint:check": "tslint --project tsconfig.json", | |||
| "docs:2": "mkdir -p docs/1-Guides && mkdir -p docs/2-API && cp documentation/*.md docs/1-Guides && api-extractor run --local && generate-ts-docs markdown -i docs/2-API -o docs/2-API && cp README.md docs/ && docsify-auto-sidebar", | |||
There was a problem hiding this comment.
Rename: replace the script docs of today by yours (and remove typedoc from the package.json). Your generated documentation looks clearly better ;)
There was a problem hiding this comment.
As the new script relies on the *.d.ts files, you should edit the https://github.com/dubzzz/fast-check/blob/master/.travis.yml#L63:L76 script and add npm run build:publish-types before the existing npm run docs (and remove mkdir from the travis step as you already do that in the script itself).
package.json
Outdated
| "lint:check": "tslint --project tsconfig.json" | ||
| "lint:check": "tslint --project tsconfig.json", | ||
| "docs:2": "mkdir -p docs/1-Guides && mkdir -p docs/2-API && cp documentation/*.md docs/1-Guides && api-extractor run --local && generate-ts-docs markdown -i docs/2-API -o docs/2-API && cp README.md docs/ && docsify-auto-sidebar", | ||
| "docs:2:publish":"gh-pages -d docs" |
There was a problem hiding this comment.
Remove: already handled by my travis script - We can maybe add it later (another review and commit)
|
Cool, I am glad you like it! I have a lot more work to do for sure, and I will address your feedback. Just thought I'd mention some of the other things I haven't yet finished: One thing I was wondering about is "Edit on github". For it to work at least for the guides, I'll need to tell the docsify-init script that the target directory for "edit on github" is not the same as the build directory where docsify stuff end up. I'll fix that. Another thing that seemed to pop up are the links to the markdown files, they are absolute so they lead to the github site. But they can be made to work exactly the same on github and on the docs site if they are
Currently the automatic sidebar generator sorts by the prefix (e.g. the folders 1-Guides 2-API become "Guides" and "API" in the sidebar) but maybe I can make it easier to customize to make it work better with this relative linking structure. |
|
Ok I believe I managed to address all fedeback, updated the docs script and the travis publish script, the npm lockfile (removed yarn one), got rid of gh-pages package and script; In addition, I moved the guides to a "1-Guides" subdirectory and updated all the links so they work on github, and in the documentation; in addition the absolute README links are transformed to relative ones for the documentation version of the readme only to ensure they continue to work on npm and github. A slightly different generator updates the sidebar too, which gives more control over how the sidebar content is displayed and more control over directory names too, so if you dislike 1-Guides and 2-API let me know which names you would prefer. |
|
By the way, the search results are pretty cool 😀 |
|
Great job ;) |
Migrated the doc from typedoc to docsifyjs. Pretty glad of the final result Migration PR was dubzzz/fast-check#343
They were all moved into `documentation/1-Guides/` by dubzzz/fast-check#343
Hi!
I tried to generate a cool looking documentation page - you can preview it here: https://spion.github.io/fast-check/
It uses api-extractor, a custom fork of docsify with improved full text search and a custom fork of Microsoft's API Documenter that generates fewer markdown files. It combines the documentation directory with the generated docs into a single site with two sections (Guides and API)
Let me know what you think?