-
Notifications
You must be signed in to change notification settings - Fork 64
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
typedoc tutorial #11
typedoc tutorial #11
Conversation
was this too much? I can reduce the changes and have only the md contributed. please advice, thanks |
Sorry, I haven't had time to review this though I would like to include it. I like the idea of generating examples. What would be the process for keeping that up-to-date? |
I'm not 100% sure what you mean with "keeping up to date". I can think on the following ( please add more examples ) : 1 - supporting changes in typedoc syntax that are backward incompatible ? This are my thoughts about how each can be tackled with the current design: 1 - Tutorial documents the basics and is oriented to people with no jsdoc experience. It doesn't try to be a manual. If you break this basic contracts believe me that the tutorial being outdated will be the least of our problems :) That being said, perhaps I can write some specs against the .json AST output (or a simpler output like markdown) just to make sure the tutorial output contains what we expect for each snippet. But I would do that after we have a descent tutorial version - if not maintaining this specs at the same time we write it could be painful.... 2 - the tutorial is compiled with typedoc with the CLI on each build (see below) that's a minimal way of keep it compatible with the CLI 3 - new features - i think is a matter of "definition of done" perhaps asking people that update the tutorial if they introduce new APIs on PRs ? And also specs in the tutorial ? I'm not sure, how are you handling that now ? I think that's something the authors / team should decide. BTW : I added a lot of content in my project :- this PR is outdated - I didn't want to change it more until I have news of you |
Just in case , a couple of comments about how the tutorial is written and output generated that I feel I didn't explain very well, since it could help on a strategy to keeping up to date. Is written in a format very similar to markdown with some handlebars helpers mostly for code snippets and links. This handlebars document is then translated to two outputs : The markdown output is ready to be used but what's interesting is what happen with the .ts output. Notice that the tutorial text is on line comments while the code snippets and its jsdocs are output as real code which is then compiled with typedoc. Since links in the handlebar document are written using a helpers links there point to the correct typedoc .html page so the user can see how the output looks like. OOT : Also alternatively the .ts file can be compiled with docco to generate a good looking document with links that's what we are using in my team now for new hires BTW - the current content is enough now for my team but There are some sections that still need to be grasped (I added TODOs) - If we go ahead with this I can take the time to do it and update this PR / branch. Thanks |
Yeah, I was mainly asking about the build. My understanding is that, we will want to run the build if someone changes the I finally was able to launch jekyll locally. I really like the way the tutorial looks. I'll have to spend more time looking at it but I'd love to merge this PR. |
Nice to know, remember that I added much more content here: https://github.com/cancerberoSgx/javascript-documentation-examples/tree/master/examples/typedoc-tutorial-basic Perhaps too much for a "basic" tutorial - After we agree on the infrastructure we can discuss the content :) |
I believe the website covers basically everything that this was intended to add now, particularly with the addition of the https://typedoc.org/example/ page and documentation for all supported tags added in 0.23. Thank you for this though! |
Notes:
THanks