docs(docs-readme): fill out docs-readme output target #1332
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
rwaskiewicz
force-pushed
the
rwaskiewicz/readme
branch
2 times, most recently
from
fd41dce to
3e164d4
Compare
rwaskiewicz
requested review from
alicewriteswrongs and
tanner-reits
and removed request for
a team
docs/config/cli.md
Outdated
| | `--debug` | Adds additional runtime code to help debug, and sets the log level for more verbose output. | | | ||
| | `--dev` | Runs a development build. | | | ||
| | `--docs-readme` | Generate `readme.md` docs based on the component types, properties, methods, events, JSDocs, CSS Custom Properties, etc. | | | ||
| | Flag | Description | Alias | |
There was a problem hiding this comment.
My editor did all this whitespace formatting w/o asking me 💢
I can back this out if folks don't like it
|
Is there a preview link? The |
There was a problem hiding this comment.
I learned a lot reviewing this PR. This is overall a great feature and the new docs capture this well 👌
One optional suggestion: do we have references of open sourced generated readme files that we can maybe link here as example for users to see "the whole thing" given an actual component used in a real world project?
We don't - other than say, the Ionic Framework source code (but even then, that's likely to change over time). I think what I'd like for us to do at some point is to be able to embed a little component in the page, and show the compiled README file to the right of it (similar to the Ionic Framework Site's playgrounds). We're not there quite yet, but I'd like to get there sometime later this year |
|
Alright, I need to backport these docs - I'll do that when I get a moment. |
|
|
||
| If your project has a `docs-readme` output target configured in your Stencil configuration file, the Stencil [build task](../config/cli.md#stencil-build) is all that's needed to generate README docs: |
There was a problem hiding this comment.
Should we keep the 'build task' language here? I think maybe I would lean towards calling it the 'build subcommand' here, 'build task' seems like some internal terminology leaking out a bit here
There was a problem hiding this comment.
(there's another usage of it below on line 37 too)
There was a problem hiding this comment.
👍 updated in ef12b55
|
|
||
| This will cause the Stencil compiler to perform a one-time build of your entire project, including README files. | ||
|
|
||
| ### Using the Docs Task |
There was a problem hiding this comment.
'Docs Subcommand' maybe?
There was a problem hiding this comment.
👍 updated in ef12b55 - I went with 'Command' here
add additional documentation concerning the behavior of the `docs-readme` output target. this commit is close to entire rewrite of the documentation - it looks to fill in all details concerning the output target regarding its behavior
Co-authored-by: Tanner Reits <[email protected]>
Co-authored-by: Tanner Reits <[email protected]>
Co-authored-by: Tanner Reits <[email protected]>
Co-authored-by: Alice Pote <[email protected]>
rwaskiewicz
force-pushed
the
rwaskiewicz/readme
branch
from
ef12b55 to
b1bd7de
Compare
add additional documentation concerning the behavior of the
docs-readmeoutput target. this commit is close to entire rewrite of the documentation - it looks to fill in all details concerning the output target regarding its behavior