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

typedoc tutorial #11

Closed
wants to merge 4 commits into from
Closed

Conversation

cancerberoSgx
Copy link

Notes:

  • tutorial is written in handlebars that generates markdown. I'm doing this since the tutorial has / will have lots of sourcecode snippet and I want to show the typedoc output for each of them. So what's happening is : tutorial.hbs generates _guide/tutorial.md and tutorial.ts (which is compiled with typedoc to generate output (html and markdown). This all happens in the node.js project tutorial-src. Perhaps this is too much ? But is the best way I found to ave the tutorial markdown and its sample source code inside the site.
  • had to updagrade json gem version in Gemfile.lock since install (in linux ruby latest) fails
  • The tutorial miss a couple of important sections, but it adds IMO valuable information. I plan to work on these in the short term. If you accept this PR I will work directly on this project (my fork). If not I will complete it in my old project
  • I added a couple of sections on it, mostly "Plugins" and "configuration files" which I didn't found documentation about.
  • I plan to write another tutorial "Getting started with TypeDoc Plugins Development" , a quick introduction with the same format (markdown and snippets. I think this kind of documentation would be great to have in the site. Do you think I should PR also that in this project ?
    THanks

@cancerberoSgx
Copy link
Author

was this too much? I can reduce the changes and have only the md contributed. please advice, thanks

@aciccarello
Copy link
Contributor

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?

@cancerberoSgx
Copy link
Author

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 ?
2 - command line options that might change (backward incompatible) ?
3 - new tags or new CLI options (backward compatible) ?

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

@cancerberoSgx
Copy link
Author

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

@aciccarello
Copy link
Contributor

Yeah, I was mainly asking about the build. My understanding is that, we will want to run the build if someone changes the tutorial-source directory.

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.

@cancerberoSgx
Copy link
Author

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 :)

@Gerrit0
Copy link
Contributor

Gerrit0 commented Jun 26, 2022

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!

@Gerrit0 Gerrit0 closed this Jun 26, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants