Current API docs are for various versions of alpha, is this intentional?

One of the biggest issues with examples on dojotoolkit.org was that new releases of dojo or new releases of browsers would leave examples broken. Without a way to monitor or identify these issues, we could only hope that a user would report the issue sooner, rather than later.

For dojo.io, examples should include unit tests and be structured in a way that automatically verifies that the example works with the latest version of dojo, or if it is deprecated any only works with the libraries used in the example.

@vansimke commented: Not sure if this one is still required with our new take on classes with TS2.2

@dylans commented: This may morph into a look at composition and mixins when working with Classes would be my guess.

This document will focus on the concept of reactive programming and how it differs from traditional techniques. It should outline what reactive programming is and the advantages that this technique has when applied to front-end development.

We should have a comment system in the blog, probably something like Disqus.

When dojo.io is deployed, all of the demo projects that support the tutorials need to be zipped up and made available to be downloaded from the dojo.io site.

Discussion

As far as I am aware, the solutions we have for web editors for tutorials have fairly challenging limitations.

• Do not integrate to TypeScript services, meaning Dojo 2's intellisense is unavailable in the editor. This severely limits the ability to demonstrate the advantages of Dojo 2, like CSS Modules and the rest of the types for @dojo as well as not demonstrating to the user that as they create code, they get the follow on intellisense of their changes.
• Have demonstrated that they will likely be difficult to update as we update our tooling/versions/etc. and make it difficult to test the tutorials to make sure they continue to function.

I have done a really simple POC to see how difficult it is to get the monaco-editor to work in dojo.io. Here is the output of that simple POC:

The code for that is as follows:

---
title: Monaco Example Tutorial
layout: tutorial
overview: An example of the `monaco-editor` as a tutorial
---

# Monaco Example Tutorial

Let's see how this goes...

<div id="container" style="height: 800px; border:1px solid grey;"></div>

<script type="text/javascript" src="/editor/monaco-editor/min/vs/loader.js"></script>
<script>
	require.config({ paths: { 'vs': '/editor/monaco-editor/min/vs' }});

	window.MonacoEnvironment = {
		getWorkerUrl: function (workerId, label) {
			return 'monaco-editor-worker-loader-proxy.js';
		}
	};

	require([ 'vs/editor/editor.main' ], function () {
		monaco.editor.create(document.getElementById('container'), {
			value: [
				'function x() {',
				'\tconsole.log("Hello world!");',
				'}'
			].join('\n'),
			language: 'typescript'
		});
	});
</script>

And to the deployment I had to run the following:

grunt generate && rm -rf _dist/editor && cp -r site/editor _dist/editor

Path forward

If we were to create a package (e.g. @dojo/web-editor) we could inject additional opinionated way of editing/running additional Dojo 2 application on the web. Here are the high level functionality tasks I would see us needing to do:

• Wrapping monaco-editor to make it super easy to "plop" onto a page. I believe at this point, moanco-editor would solve "out of the box" the following:
  • Ability to edit files of TypeScript/CSS/HTML/JavaScript
  • Ability to integrate to TypeScript services to get whole project code intelligence that is equivalent to the functionality of vscode.
  • APIs to update/display/retrieve file content.
• A way to provide a manifest file of a "project" to be used with the editor to be able to edit and run an application in the browser
• Provide an API/mechanism for navigating the files of the manifest, editing them and having that update the "project"
• Figure out a way of doing what we need to do with postcss to allow CSS modules to be changed and emitted in browser
• Provide an offline build process that can bundle manifests into projects that can be downloaded (or published to npm)
• Provide a way of updating dependencies and updating the manifests in line with changes to the CLI.

The Future

Additional functionality that we would want but would be delivered in the future:

• The ability to generate manifests from dojo CLI and potentially take a manifest and generate an application.
• Creating new projects/code examples and being able to share them.

There is a 100,000 request limit per month on github pages. We should see if the limit can be updated. This is also directly related to #25

This issue is to research/decide on features, switching between versions of API docs, how directory structures are laid out. May need second issue for design portion (TBD).

Dependent on the outcome of #39

Related to #45

Going to https://dojo.io shows a privacy error.

Currently there are several places in the dojo.io source where code snippets are manually copied from demo files into markdown files. Ideally, the markdown files should be able to link directly to the code snippets so that they don't get out of sync.

Depends on Issue 31.

Update tutorial's index.md files to include references to source code files instead of duplicating the code.

Consider adding one (or more) tutorials that help new users understand the nuances of authoring non-trivial widgets.

If I'm working on the tutorials locally (not using Plunkr), I do not want to see the Plunkr panel and it takes up a lot of room on the screen. Would be nice to allow that panel to be minimized.

I had some similar thoughts to @jason0x43 when looking at the Dojo API docs that he mentioned in theintern/intern#727 (comment)

TypeDoc runs on Intern, Leadfoot, and Dig Dug. Unfortunately, the generated output isn't super well organizaed. Ideally we'd have something that looks structurally similar to Leadfoot's and Dig Dug's API docs now (not necessarily with the same styles; the bootstrap-like aesthetic of the default TypeDoc docs is probably fine), with top level modules in a side bar, and without a lot of noise in the property and function lists.

A stretch goal would be to improve TypeDoc's ability to handle arbitrary markdown files (besides README) so that we could just use TypeDoc to generate the entire docset for a given tool (expository docs as well as API docs).

Note that I'm not saying we need the left side navigation, but in general there's a lot of noise in the docs that make them less efficient to parse and use, and quite a bit of duplication of information in places.

A few points that I may have made elsewhere:

• Why are things called Globals when they're not
• Inside each package we repeat the package name 3 times at the top of the page (e.g. see the top of http://dojo.io/api/core/v2.0.0-alpha.26/ )
• I'd probably like to see usage first (e.g. the constructor)
• It would probably help for an index page to show all of the top level constructors, and then have a will to drill down and see more details, instead of having to click into every global to get details... e.g. the index page should list all the constructors for all the globals perhaps?

We state that cli-build-webpack is included in cli. This is incorrect - it is a separate install.

This article will discuss the three vDOM abstraction functions and how they relate to each other and the underlying “h” function. This section should discuss how Dojo 2 uses HyperScript, but should not get into too much detail on that. Links to HyperScript documentation should be provided, if needed.

@dylans commented:

At some point I'd like an aside that explains why it's called a projector (especially for Germans where a projector is called a beamer)... let's open a separate issue to add an aside explaining the term, or to make sure we later cover it in the virtual dom article.

Configure the dojo.io site and project master branches to continuously deploy the site and API documentation

The fourth tutorial's "finished" state doesn't work. This is caused by the lack of a "key" property with a unique value for each widget. Review each tutorial and add keys where appropriate. Also, update index.md's to discuss.

The search seems to work only if it lands on an exact entry you select, but it doesn’t offer up partial matches. As an example, if you type “iteration” it matches nothing and doesn’t even try to provide results. if you type “has” it drops down results to click on, but doesn’t refresh the page with results.

New website have a community section:

• https://gitter.im/dojo/dojo2 for discussion
• Discourse (when live)
• dojo/meta
• support options (SitePen)

We need to build an intermediate data format for API docs (i.e. JSON or markdown). Goal is the ability to rebuild the site without checking out all of the repos.

We will need some things like a mobile menu, tooltips, etc. from Dojo2 for the website. Define list here so we can get them created (if needed).

Issue 23 mentions the ability to add additional commentary about a concept that doesn't directly fit into the tutorial's goal. We need to be able to create something like an "aside" to support this type of content.

This tutorial will walk the learner through the compilation and deployment of a Dojo 2 application to production

grunt-dojo2 and cli-build were both updated to rename CSS modules as .m.css (instead of .css).

What this means for you!

• Any CSS file that is imported, i.e., import * as styles from './styles/myfile.css' needs to be renamed to .m.css, and the import statement updated: import * as styles from './styles/myfile.m.css.
• Other CSS files (main.css) do not need to be renamed.

The Quick Start in the readme is totally wrong.

RSS support would be great 😄

Since the converter takes a while for each of the projects to run, research a solution where the TypeDoc generator can be run independent of the converter.

Plunker was down this morning which looked bad. Need a fallback if/when their service is down.

Tutorial one has been changed to remove the direct manipulation of an element's styles. This change should be reflected in the other tutorials as well.

We should be able to disable plugins in TypeDoc such as the syntax highlighter through our custom TypeDoc setup.

Currently, the scaffolded app created by dojo create contains elements that were not considered when the first tutorial was written. This tutorial needs to be adjusted to point the learner toward downloading the pre-built project until a longer term solution is available