Add inverse component/sim lookup

In phetsims/tasks#980 (comment) @zepumph added a list of sims with an expandable menu listing the common code components used within it.

It would be extremely helpful to also have the inverse of this list. That is, add a list of common components with expandable menu listing the sims which contain that component. This is a stop-gap measure until a complete, functional style guide is a reality.

The long-term vision for binder is for each common component to have its own page (eg. ComboBox) which contains visual examples of the component in each sim.

Create a package.json

Right now we are using 'marked' and 'puppeteer' but it's not official yet.

Set up automatic github interfacing

This is down the line, more of a long term goal, but wouldn't it be nice if there was a controller that would pull repos, and then run the generation, and push the updated documentation to github. That would help to automate these docs and keep them up to date.

Run on bayes

This is down the line, more of a long term goal, but if this ran on bayes, perhaps a cron job that ran once a day, then the documentation would stay very up to date. Again, this is an enhancement or version 2.0 sort of feature in my book.

Wishlist of common components to add to lookup

In reviewing #25 I realized that there are many common UI components which are missing from the components-by-sim and sim-by-components lists in binder. Currently, it looks like the only components included are the ones which have associated .md files in the style guide.

I took a look around sun and scenery-phet and I've come up with a preliminary wishlist.

A few caveats:

We have SO MANY BUTTONS, and I don't think it would be useful to have an entry for every possible kind of button in sun. That said, buttons in scenery-phet tend to have specific purposes (e.g. PlayPauseButton) and I think it would be useful to be able to look up these sorts of buttons.
Inheritance is tricky, so there may be some redundancies in the list, though I've tried to avoid this as much as possible.
I'm very open to developer suggestions/pushback on this list, so please don't take it as the gospel @zepumph.

PhET doesn't checkin pack-lock files

@mbarlow12 right now, PhET devs have turned off the use of package-lock files in npm, and we aren't checking these in. I don't think that binder should be treated any differently. See phetsims/chipper#578 (comment) for the central issue and steps to turn off package-lock creation for your environment.

npm config set save false

Next steps for Style Guides and Binder

This week @zepumph and I created an initial draft for Binder, which combines hand-written markdown documentation with automatically generated information about component usage. The results are published on https://phetsims.github.io/binder/

Currently, we are only including information on Checkbox, ComboBox and HSlider, though it would be easy to add other components.

@amanda-phet the markdown files are located in https://github.com/phetsims/sun/tree/master/docs . Can you please review them, update them and review https://phetsims.github.io/binder/ to see what else should be done at the moment?

Subcomponents need a way to opt out of registering if their Parent component "covers" them

Example came up in keyboard nav meeting today. AccordionBox uses ExpandCollapseButton, and the custom html for AccordionBox (that includes ECButton in the PDOM is potentially different from the interaction pattern of ExpandCollapseButton itself. How should this look in the style guide?

@terracoda is this summing up what you were wondering about during the meeting?

Notes:

@emily-phet noted this is a very a11y specific problem, and we don't really have to worry about this until we want ExpandCollaspseButton (the subcomponent) in the style guide.
Even so we may need to handle this in other places, so I thought an issue would be good.

HSlider documentation should be renamed to Slider

From phetsims/sun#380, now the logic is in the Slider file, with HSlider and VSlider as convenience types. The documentation should reflect that and just say "Slider"

Add build-local.json check for local development

We've hardcoded the address of a local development. @zepumph noted in #12 that this should be configurable for different environments. To allow for this, we'll add a check in ~/.phet/build-local.json for the following keys:

{
    "localHostURL": "http://localhost",
    "localHostPort": "8080"
}

Since node's http-server runs the server configured above, those will be the defaults.

Add build-local.json check and defaults for setting the local dev server URL in getFromSimInMaster.js.
Add config options to README

Binder is broken and not built every night

Looks like it needs to get transpiled before running. I'll add this to daily grunt work.

Redundant/broken list of sims under "Simulations and their components"

Related to phetsims/tasks#980 (comment)

Under http://phettest.colorado.edu/binder/doc/#sims, there are two lists of simulations. The list at the bottom which binder autoscrolls to when clicking "Simulations and their components' in the sidebar is not functional.

branch: async

The branch is for implementing asynchronous building of the sim and using ES6 features.

run getFromSimInMaster in parallel

We could open more than one page in puppeteer.

How to handle the same a11y documentation for different components

From phetsims/sun#361, I see a need for single a11y documentation (like interaction pattern and sample html) to document AccessibleSlider.js. But that file is mixed into many different common code types (and more to come). Currently the way that binder is set up, we are generating documentation by component, because of the way that InstanceRegistry is set up.

I think the best way to proceed is to have a single component md file that has this content, and then in all the other files, we point to the one saying, "a11y interaction is the same as {{base-component}}." So in Faucet.md you will be pointed to HSlider, since it is the same interaction. This will also be good to do with RadioButtonGroup vs VerticalAquaRadioButtonGroup.

test issue

Checkbox

acid-base-solutions

Where should the component documentation be?

As part of the component documentation, we plan to write MD (markdown) files that describe the corresponding JS (javascript) files. Binder will combine the MD files with automatically generated information to create the overall documentation.

When I recommended to put the MD files next to the JS files, I was told that there was a prior consensus to put the documentation files "elsewhere". I don't know what the arguments were for putting them elsewhere, but I recommend to keep them in the same directory as the component they document, for the following reasons:

PRO-1. This will encourage developers to be more aware of the MD files, and hence to see them, read them, and keep them up-to-date. For example, if a developer is changing a feature in ComboBox.js, they will have a better chance to update ComboBox.md if it is nearby.
PRO-2. Subtly different than the first point: The ComboBox.md and the ComboBox.js should generally evolve together. It seems odd that if we are updating ComboBox.js and ComboBox.md that we would push commits to two separate repos. This is more of an argument for the same repo than the same directory.
PRO-3. It has worked well to keep other related files adjacent to the primary file. For instance, ComboBox.js would be next to ComboBoxIO.js and ComboBoxTests.js and now also ComboBox.md. Also, then you can look at a component JS file and easily see if it has all of its other related files, without having to hunt elsewhere.

I do not know what arguments were given for keeping the MD files separate from the JS files, but here are some reasons I can think of:

CON-1. This will clutter up the already crowded source code directories. In my opinion, the advantage of PRO-3 seems to outweigh this.
CON-2. The source code directories are named "js" and hence should only contain JavaScript, not other file types. This seems like a reasonable argument, but not sure if it outweighs the PROS taken together.
CON-3. Keeping them in the same repository could create commit conflicts if developers are working on the design files at the same time as the developers are working on the same repo. In my opinion, this problem is minimal, especially if designers are using the GitHub website to make changes.
CON-4. If the MD files require image files, we probably wouldn't want to keep those in the js/ folder and it could be odd to separate them from the MD files.

If we combine PRO-2 with CON-2, the conclusion would be to put the MD files in the same repo as the component, but in a different directory (perhaps docs/ or md/). What was the recommended location for the MD files from the prior meeting?

Create binder

branch: yamldocs

Proposed in #15, the binder branch will handle parsing of YAML front matter within the build process. We'll make use of https://github.com/jonschlinkert/gray-matter.

Add data about each component

Related to #5, the style guide show this information which is not presented in the binder view at the moment:

Here is additional information from the Style Guide that we should add to the document:

Number of published sims with component: [number]
Sims with component (not necessarily published): [list of all sim repos]
Published sims with component: [list of sim links]
Published sims with element a11y enabled: [list of sim links]

@zepumph can you work on that part? You should be able to leverage the existing data for the first two bullets, and I think you referred to some metadata service that would help with the latter two.

pattern for stripping binder documentation

I see 12 occurrence of

assert && phet.chipper.queryParameters.binder ...

For example, in Slider.js:

// support for binder documentation, stripped out in builds and only runs when ?binder is specified
assert && phet.chipper.queryParameters.binder && InstanceRegistry.registerDataURL( 'sun', 'Slider', this );

Using assert in this way (to strip out things other than assert) seems a bit questionable. Labeling for discussion at developer meeting.

Make things pretty

Today is dev meeting (relating to phetsims/tasks#980), it was mentioned that perhaps it would be good to get @chrisklus, the front-end whiz, in on this repo to help out making UI improvements. I'm not exactly sure what this will look like, but I'm making an issue to begin the discussion.

@chrisklus perhaps you just want to go for it, or start working with a designer. Or maybe we can talk and I can give you a tour of the limited things I know about the front end. For example it is using a few templating technologies, like handlebars and perhaps mustache too. There is also some fancy stuff in there about compiling the common code markdown files into the generated binder output.

Add YAML front matter to documentation

YAML front matter is a feature used by Jekyll and other static site generators to add metadata to simple .md or html files. In building the binder documentation, this may allow us to effectively register various common code components for display within a single or multiple markdown documents.

Using a library such as gray matter, we can add and parse metadata about the component(s). Branches have been created in sun and binder to test this feature.

Host docs from gh-pages branch

Trouble found from the changes in phetsims/tasks#936. GitHub mandates that pages use adocs/ directory. So for binder, we'll follow the method of scenery and use a new gh-pages branch to properly host the generated HTML.

create modular structure

Right now we have two files. One creates html for data, and the other generates the data, uses the first file, and then writes the documentation. I would rather have small modules that are responsible for each feature that we want with the style guide. Here is what I propose so far:

generate.js - manager file for the whole script, will create an html documentation file, potentially responsible for option parsing
the two files that we have right now will be part of the fromSimInMaster module (or another name), and will be renamed to getFromSimInMasterData and getFromSimInMasterHTML.

I'll see how far this takes me.

(node:38752) UnhandledPromiseRejectionWarning: TypeError: Cannot convert undefined or null to object

To see what other sims use ProbeNode for phetsims/wave-interference#24, I instrumented ProbeNode and ran:

cd js/; node generate.js;

and received this error:

loading: wave-on-a-string
wave-on-a-string PAGE LOG: enabling assert
wave-on-a-string PAGE LOG: loaded wave-on-a-string
(node:38752) UnhandledPromiseRejectionWarning: TypeError: Cannot convert undefined or null to object
    at Function.keys (<anonymous>)
    at sims.forEach.sim (/Users/samreid/github/binder/js/createHTMLString.js:25:41)
    at Array.forEach (<anonymous>)
    at createHTMLString (/Users/samreid/github/binder/js/createHTMLString.js:24:8)
    at __dirname (/Users/samreid/github/binder/js/generate.js:43:16)
    at <anonymous>
    at process._tickCallback (internal/process/next_tick.js:160:7)
(node:38752) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: 1)
(node:38752) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

Add fast html compile option from generated json instead of sim instance registry

Since we generate a json doc anyway when accessing the sims, a quick way to regenerate the html file will be very useful. Perhaps a new npm/grunt task?

binder TODOs

For phetsims/tasks#1017.

There are 4 TODOs in binder without an associated issue. All four are either pointing out recommended improvements or possible weaknesses, so I'm linking them here to be tracked.

With the transition of binder to be built with react in #26, I'm not sure how many of these will still be relevant and need or work or be replaced/not needed. Leaving unassigned until the relevance of this code is determined.

Sidebar links don't add a fragment hash

When you click an item in the sidebar, the webpage navigates to the desired component very nicely. It could be nice though to have the url fragment update with that change too.

This is a small issue, but I believe that it may be useful when trying to share this resource for an individual component.

What do you think @mbarlow12?

phetsims / binder Goto Github PK

binder's People

Contributors

Watchers

Forkers

binder's Issues

Checkbox

Recommend Projects

Recommend Topics

Recommend Org