write inline instructions on generating preview of reference (again!)

add temp section: questions to ask section

Author: nbogie

contributor_docs/contributing_to_the_p5js_reference.md

@@ -223,19 +223,10 @@ Multiplies a vector by a scalar and returns a new vector.
 
 A hypertext link HTML element can be used within a function description to link to the documentation of a relevant function or variable.
 
-The url should be of this "fragment" or "hash" form: `#/p5/ + function_or_variable_name`.  It should _not_ include a direct link to the website.
+The url should be of this "fragment" or "hash" form: `#/p5/ + function_or_variable_name`, e.g. `#/p5/circle`, `#/p5/DEGREES`. 
+   It should _not_ include a direct link to the website.
 
-TODO: 
-Correct this url rule - the `p5` prefix is not universal.  Why, for example, is p5.Vector linked with `#/p5.Vector` and not  `#/p5/p5.Vector` (which it resolves to in the website):
-```
-#/p5.Image
-#/p5.Element
-#/p5.Texture
-#/p5.Framebuffer
-#/p5.Vector
-#/p5.Renderer
-```
-END-TODO
+TODO: correct this rule.  what about p5.Vector, p5.Graphics, etc.  what about methods of those classes ? p5.Vector/setMag?  static methods?
 
 Examples:
 
@@ -677,7 +668,7 @@ For more on `describe()` visit the [web accessibility contributor documentation]
 
 With all the above you should have most of the tools needed to write and edit p5.js reference comments. However, there are a few more specialized usages of JSDoc reference comments that you may come across in p5.js. These are situationally useful and not something that you need often.
 
-TODO: perhaps just link here to [./jsdoc.md](./jsdoc.md)?
+TODO: either just link here to [./jsdoc.md](./jsdoc.md) or bring all of that into this document.
 
 <!-- TODO: done to this point -->
 
@@ -763,12 +754,53 @@ Class constructors are defined with the `@class` tag and the `@constructor` tag.
  */
 ```
 
-
 ## Generating and previewing the reference
 
-In some editors, such as vs code, you can hover over a function or variable to see immediately - in a pop-up - a rendering of the information from the documentation comment above it.  This can be a useful first quick preview.
+### A quick first in-editor preview for vs code users
+
+In some editors, such as vs code, you can hover over a function or variable to see immediately - in a pop-up - a rendering of the information from the documentation above it.  This can be a useful first quick preview, though it won't show everything - it won't run your code examples, or show linked images, for example.
+
+### Previewing your work on the website, locally
+
+At some point you will want to preview how your changes will look on the website.  This involves run the website locally and having it import your p5.js code from a branch of your repo.
+
+Note: the following instructions currently co-exist here and in the website repo file: [/docs/scripts.md in the section "testing the docs of your fork"](https://github.com/processing/p5.js-website/blob/2.0/docs/scripts.md#testing-the-docs-of-your-fork)).
+(TODO: check what to do about this duplication of preview instructions.)
+
+Steps: 
+
+1. Commit your changes to a local branch of your fork of the p5.js repo.  The changes don't need to be pushed to github for this purpose, but they do need to be committed on a branch.
+1. Clone [the p5.js-website repo](https://github.com/processing/p5.js-website/tree/2.0) locally.
+1. In your new p5.js-website repo, check out the branch "2.0".
+1. In your new p5.js-website repo, run `npm install`
+1. In your new p5.js-website repo, run the following command, using the path to your local p5.js repo before the `#`, and the name of your branch after the `#`:
+
+```sh
+npm run custom:dev path/to/local/repo#yourBranch
+```
+
+For example, if your work is in a branch called `my-amazing-branch` on a local p5.js repo called `p5.js` as a sibling directory next to the current p5.js-website directory, you could run the following:
+
+```sh
+npm run custom:dev ../p5.js#my-amazing-branch
+```
+
+This will build the local website reference pages from the data in your branch and start a development preview of the website.  
+
+6. Find the URL that is logged in the console and visit it in your browser in order to test out your changes.
+
+If you prefer to preview work that's already on github, you can do so.  Use the repo url instead of its local path, as follows:
+
+```sh
+npm run custom:dev https://github.com/yourUsername/p5.js.git#yourBranch
+```
+#### Resetting your changes
+
+When you're done with this preview, you can run this command to reset your changes:
+```sh
+npm run custom:cleanup
+```
 
-To check more thoroughly, it is necessary to use the website software.  You can clone and run it locally.  There are some convenience scripts to help with pointing it at your repo and branch and starting the server so you can preview your documentation.  Instructions for these are in [/docs/scripts.md#testing-the-docs-of-your-fork](https://github.com/processing/p5.js-website/blob/2.0/docs/scripts.md#testing-the-docs-of-your-fork).
 
 ## Next steps
 
@@ -853,14 +885,29 @@ On the p5js repo...
 
 ## TODO:
 * move this TODO section out before submitting PR
+* Finish and place the flow diagrams for doc-gen.  ?where?
 * Replace first example in Adding examples - it doesn't run no setup or draw.  allowed but v unusual in the repo.
-* whether to omit @method tag or not?
-* update/deprecate @chainable?
-* check if we want to encourage  text between code examples? (e.g. for gradual introduction and explanation of more complex use-cases).  Or is there a risk the user misses critical detail because it was in the "examples" section?
 * perhaps acknowledge that there are limits to the types info we can carry in JSDoc and that types are currently sometimes patched in patch.mjs.
+* Do a more thorough write-up of how to generate and preview the reference, written for someone who needs to do it to check their work, and has no other instructions.
 * address type-generation here?  (that the JSDoc comments aren't ONLY used for the reference!)
 * find (and use) any recommended mechanism for adding asides as (e.g.) (accessible) default-collapsed sections.
 * add section on minimising unnecessary concept dependencies in code examples? Where's the balance between cool examples vs ones that can be most easily understood?  What's the line with regard to generating engagement with examples?  (If it belongs in the style guide, develop it more there and link to it from here).
+* check if tagging incomplete snippets in the markdown as js is harmless (e.g. doesn't break the highlighter library).  It provides useful best-effort syntax-highlighting in some contexts, helping to spot errors.
+* ? run a comprehensive broken-link check? broken example check?  develop one?
+* add a ToC?  there's one on the side panel but it doesn't give a good overview.
+
+## TODO: Questions to ask
+* What's the url-forming rule for in-documentation linking?
+```
+`#/p5/circle` goes to `p5/circle` but 
+`#/p5.Vector` goes to `p5/p5.Vector`
+???           goes to `p5.Vector/setMag`
+???           goes to `p5.Vector/fromAngle`
+
+```
+* The existing guide shows how to write examples with no setup or draw fn, which are auto-wrapped in setup. Codebase doesn't use this.  Downplay / remove the mention of this mechanism?
+* Accept this? "Generally, each example should be a self-contained complete sketch that will run on the reference website and which could be run directly if pasted into the web editor (for example)."  
+* Accept the following?: Multiple examples are not always separated by @example in the repo.  JSDoc says they should be, so i've said that.  The guide previously said just put a blank line and then new codeblock.
 * assets: 
   * ? say anything about licensing (e.g. for assets)
   * ? say anything about preferred file formats (for size, for browser compat, for licensing?)
@@ -869,17 +916,10 @@ On the p5js repo...
   * text size
   * color choices (wrt color blindness, also contrast)
   * ?reduced-motion?
-* ? run a comprehensive broken-link check? broken example check?  develop one?
-* add a ToC?
-* check if tagging incomplete snippets in the markdown as js is harmless (e.g. doesn't break the highlighter library).  It provides useful best-effort syntax-highlighting in some contexts, helping to spot errors.
-* Do a more thorough write-up of how to generate and preview the reference, written for someone who needs to do it to check their work, and has no other instructions.
-* Finish and place the flow diagrams for doc-gen.  ?where?
-* Document how to link to other related functions from within a function description.
-e.g. 
-```
-See  the <a href="#/p5/push">push()</a> and <a href="#/p5/pop">pop()</a> functions.
-```
-* confirm my stipulation of @example between examples - a lot of p5 codebase does this, but the guide previously said just put a blank line and then new codeblock.
-* update how to use any asset inside code example
-* check assertion: "Generally, each example should be a self-contained complete sketch that will run on the reference website and which could be run directly if pasted into the web editor (for example)."  Downplay / remove the mention of excerpt-examples getting automatically wrapped in a new setup() function ?
-* Replace use of sin documentation as first encounter? - it's too long and is almost all example code, not doc comment.
+
+### TODO: Questions to ask: low-priority
+* Do we want to encourage descriptive text _between_ code examples? (e.g. for gradual introduction and explanation of more complex use-cases).  Or is there a risk the user misses critical detail because it was in the "examples" section?
+* Non-technical: Replace use of sin documentation as first encounter? - it's too long and is almost all example code, not doc comment.
+
+## Resolved questions
+* Whether to recommend omitting @method tag or not? I'm assuming no: its presence reduces ambiguity and helps codebase search.