search

numberscope / frontscope

Numberscope's front end and user interface: responsible for specifying sequences and defining and displaying visualizers
MIT License
7 stars 15 forks source link

Documentation site overhaul for alpha #486

Closed gwhitney closed 1 week ago

gwhitney commented 3 weeks ago

By submitting this PR, I am indicating to the Numberscope maintainers that I have read and understood the contributing guidelines and that this PR follows those guidelines to the best of my knowledge. I have also read the pull request checklist and followed the instructions therein.

There will be several commits to this PR; they will be summarized by editing this message, as added. Once all of the planned commits are pushed, the "draft" marking will be removed. Putting this in as a draft PR provides the opportunity for anyone to do some pre-review of the proposed appearance and content of the docsite, for example, to evaluate how well it harmonizes with the frontscope itself.

Features so far in this PR:

Resolves #46. Resolves #179. Resolves #319. Resolves #320. Resolves #323. Resolves #425. Resolves #483. Resolves #487.

gwhitney commented 3 weeks ago

I suggest npm run preview as the best way to compare the frontscope with the docsite. Just be aware that this preview does not "hot update" as you change code; you have to break out of the server, re-run npm run preview, and then re-load your page.

katestange commented 3 weeks ago

The overlap problem does indeed appear to be solved in all three of my available browsers! A few notes:
(1) On the main scope page the header hyperlinks (about, gallery, documentation) are always black, but on the docs page they can change colour to purple/blue with mouseover and having visited.
(2) Also the little "home" (house) icon in the directory path at the top of whichever current page is not a colour that matches our scheme.

gwhitney commented 3 weeks ago

Both excellent points. Links should be colored uniformly throughout both the 'scope and the docs. How do we want them colored (or not)? And then the house should just be colored as any other link (as that's what it is, it goes to the root of the documentation.

gwhitney commented 3 weeks ago

I am just slightly worried that if we just use black for links in the documentation, which is mostly text and has a fair number of links, it will be difficult to see what words are links. So if you don't want any color for links (to match the current scheme in the 'scope, where there are not many links and the ones that are there are identified reasonably clearly in oher ways), then should we distinguish them in some other way in the docs? Possibly by underlining them?

katestange commented 3 weeks ago

Underline would be ok with me. Try whatever you think looks good.

gwhitney commented 3 weeks ago

OK, so I take it you would like to stick with black, like the 'scope is now, as far as the color scheme for links goes?

katestange commented 3 weeks ago

I would be ok with that. If we go for colours on mouseover/visited, I'd be ok with that if they match the colour scheme.

gwhitney commented 3 weeks ago

OK, another commit. It doesn't yet fix the two points about link styling you brought up. However, it does

(a) call checkParameters when the sequence updates;

(b) thoroughly update the Building a Visualizer documentation page (but not yet "Behind the scenes" of a visualizer),

(c) add an extensive lifecycle diagram for a visualizer.

When you have a chance, please take a look:

(a) Can you try the Turtle situation that led you to write the "BUG" comment in the code there, to see if it is resolved now that checkParameters is being called?

(b) Is Building a Visualizer clear and coherent? Has it become too complicated/detailed? If so, could you identify some material it would be safe to move to "Behind the scenes"?

(c) What do you think of the new lifecycle diagram and its placement? I was torn between putting it up near the top, and putting it at the bottom where it would sort of summarize the text. I opted for the former because the page is very long, and I was afraid with it at the bottom it would get lost. It occurs to me I could put it on a separate page, though -- would that be an improvement?

I am aware there are some graphical shortcomings of the lifecycle diagram. It is being autogenerated from a text description using a package called "mermaid", and the mermaid flowchart language does not provide control over node placement/order or general chart layout. The self-loops also come out looking very poor. I am not inclined to battle with the innards of mermaid. So I am happy to improve the diagram in terms of content/labels/nodes/connectivity, but there's not much to be done on layout. It occurs to me that someone posted a diagram maker on illustrating math, so I will take a look. But presuming that doesn't pan out, I think this is about the best we can do on layout with a text description format at the moment.

gwhitney commented 3 weeks ago

Ah it is Penrose I was thinking of. It's very general and flexible and it seems as though it could be used to do flowcharts. But one would need .domain/.style files designed for laying out flowcharts. Not sure if anyone has made such things. I will ask on illustrating math discord.

gwhitney commented 3 weeks ago

OK, that latest commit should take care of both of your link comments. On to other doc issues.

gwhitney commented 2 weeks ago

Summary of recommendations from 2024 Nov 5 meeting:

Aaron comments

Create visualizer object (constructor) --> 
Validate parameters individually (`validate()` functions) --> ...
gwhitney commented 2 weeks ago

OK I have attempted to split the "making a visualizer" documentation as recommended. I actually went for three parts: the "overview" at the top of the former monolithic page seemed like a page unto itself, so I made it so. Then I have a tour of just the components that appear in the P5VisualizerTemplate, written at what I tried to make an "introductory level". Finally, there is an attempt at a complete tour, omitting information fully covered in the introductory page, written at what I tried to make an "intermediate level" (as there is still the "Behind the scenes" page written more as fully technical documentation.

I haven't yet updated the diagrams because I will need to get D2 running and incorporating its output into the documentation results (fortunately it turns out there is an mkdocs extension that already exists for this). But in the meantime I'd be grateful for anyone who can look at what's happened so far and provide any feedback.

gwhitney commented 2 weeks ago

OK, I have made all the changes I planned in response to our last discussion; please take a look. NOTE however that now to generate the documentation you must install d2.

Now, I am just going to go through all docsite changes/fixes planned for alpha and make sure they are all done. Hopefully I will be able to mark this as ready for "official" review soon.

gwhitney commented 2 weeks ago

Oops, and in fact I need to update the CI scripts to install d2 on the test machine! Coming up...

gwhitney commented 2 weeks ago

Ah, issue #321 is still outstanding. I had marked it for discussion at our last meeting, but we didn't get to it because of the extended discussion of diagramming options. There's an extensive question near the end of the comments. If anyone is able to read and provide feedback before Tuesday, that would be appreciated. Otherwise we will discuss it then. I can't wrap up this PR until the questions there are resolved (and conversely, it seems that's the only thing remaining slated to go in this PR). Thanks!

gwhitney commented 2 weeks ago

OK, on my local machine I have an implementation of proposal 4 from #321, which is to turn the whole "description" into a link, see screenshot below. It turns out the frontscope does underline links, so you can in fact see there is a link there; I was worried there would just be no indication of a link. But having tried this, it seems to me that the description is the wrong thing to link -- it looks like the link will be to more information about the thue-morse sequence, maybe from the OEIS, when in fact what you get is the Numberscope user guide page on OEIS sequences in general. So since I definitely don't think it's the way to go and it's a pain to check in because I would have to update a number of snapshots, I didn't push a commit for this. Screenshot_2024-11-09_15-08-37

katestange commented 2 weeks ago

Currently I can't run this because it can't find d2 even despite npm run install.

katestange@ducked-tape:~/data/code/numberscope/frontscope$ npm run preview

> frontscope@0.3.0 preview
> make -f etc/Makefile preview

npm install

> frontscope@0.3.0 postinstall
> python3 -m venv .venv && cd tools && node pyrun.mjs python -m pip install -U pip && node pyrun.mjs pip install -r requirements.txt

Requirement already satisfied: pip in ./.venv/lib/python3.12/site-packages (24.3.1)
Requirement already satisfied: markdown-grid-tables~=0.3 in ./.venv/lib/python3.12/site-packages (from -r requirements.txt (line 1)) (0.3.2)
Requirement already satisfied: mkdocs~=1.6 in ./.venv/lib/python3.12/site-packages (from -r requirements.txt (line 2)) (1.6.1)
Requirement already satisfied: mkdocs-d2-plugin~=1.5 in ./.venv/lib/python3.12/site-packages (from -r requirements.txt (line 3)) (1.5.0)
Requirement already satisfied: mkdocs-semiliterate~=0.8.3 in ./.venv/lib/python3.12/site-packages (from -r requirements.txt (line 4)) (0.8.3)
Requirement already satisfied: mkdocs-awesome-pages-plugin~=2.9.3 in ./.venv/lib/python3.12/site-packages (from -r requirements.txt (line 5)) (2.9.3)
Requirement already satisfied: pymdown-extensions~=10.8 in ./.venv/lib/python3.12/site-packages (from -r requirements.txt (line 6)) (10.9)
Requirement already satisfied: python-markdown-math~=0.8 in ./.venv/lib/python3.12/site-packages (from -r requirements.txt (line 7)) (0.8)
Requirement already satisfied: markdown>=3.0.0 in ./.venv/lib/python3.12/site-packages (from markdown-grid-tables~=0.3->-r requirements.txt (line 1)) (3.7)
Requirement already satisfied: click>=7.0 in ./.venv/lib/python3.12/site-packages (from mkdocs~=1.6->-r requirements.txt (line 2)) (8.1.7)
Requirement already satisfied: ghp-import>=1.0 in ./.venv/lib/python3.12/site-packages (from mkdocs~=1.6->-r requirements.txt (line 2)) (2.1.0)
Requirement already satisfied: jinja2>=2.11.1 in ./.venv/lib/python3.12/site-packages (from mkdocs~=1.6->-r requirements.txt (line 2)) (3.1.4)
Requirement already satisfied: markupsafe>=2.0.1 in ./.venv/lib/python3.12/site-packages (from mkdocs~=1.6->-r requirements.txt (line 2)) (2.1.5)
Requirement already satisfied: mergedeep>=1.3.4 in ./.venv/lib/python3.12/site-packages (from mkdocs~=1.6->-r requirements.txt (line 2)) (1.3.4)
Requirement already satisfied: mkdocs-get-deps>=0.2.0 in ./.venv/lib/python3.12/site-packages (from mkdocs~=1.6->-r requirements.txt (line 2)) (0.2.0)
Requirement already satisfied: packaging>=20.5 in ./.venv/lib/python3.12/site-packages (from mkdocs~=1.6->-r requirements.txt (line 2)) (24.1)
Requirement already satisfied: pathspec>=0.11.1 in ./.venv/lib/python3.12/site-packages (from mkdocs~=1.6->-r requirements.txt (line 2)) (0.12.1)
Requirement already satisfied: pyyaml-env-tag>=0.1 in ./.venv/lib/python3.12/site-packages (from mkdocs~=1.6->-r requirements.txt (line 2)) (0.1)
Requirement already satisfied: pyyaml>=5.1 in ./.venv/lib/python3.12/site-packages (from mkdocs~=1.6->-r requirements.txt (line 2)) (6.0.2)
Requirement already satisfied: watchdog>=2.0 in ./.venv/lib/python3.12/site-packages (from mkdocs~=1.6->-r requirements.txt (line 2)) (5.0.1)
Requirement already satisfied: pydantic>=2.0 in ./.venv/lib/python3.12/site-packages (from mkdocs-d2-plugin~=1.5->-r requirements.txt (line 3)) (2.9.2)
Requirement already satisfied: mkdocs-simple-plugin==3.2.0 in ./.venv/lib/python3.12/site-packages (from mkdocs-semiliterate~=0.8.3->-r requirements.txt (line 4)) (3.2.0)
Requirement already satisfied: natsort>=8.1.0 in ./.venv/lib/python3.12/site-packages (from mkdocs-awesome-pages-plugin~=2.9.3->-r requirements.txt (line 5)) (8.4.0)
Requirement already satisfied: wcmatch>=7 in ./.venv/lib/python3.12/site-packages (from mkdocs-awesome-pages-plugin~=2.9.3->-r requirements.txt (line 5)) (9.0)
Requirement already satisfied: python-dateutil>=2.8.1 in ./.venv/lib/python3.12/site-packages (from ghp-import>=1.0->mkdocs~=1.6->-r requirements.txt (line 2)) (2.9.0.post0)
Requirement already satisfied: platformdirs>=2.2.0 in ./.venv/lib/python3.12/site-packages (from mkdocs-get-deps>=0.2.0->mkdocs~=1.6->-r requirements.txt (line 2)) (4.2.2)
Requirement already satisfied: annotated-types>=0.6.0 in ./.venv/lib/python3.12/site-packages (from pydantic>=2.0->mkdocs-d2-plugin~=1.5->-r requirements.txt (line 3)) (0.7.0)
Requirement already satisfied: pydantic-core==2.23.4 in ./.venv/lib/python3.12/site-packages (from pydantic>=2.0->mkdocs-d2-plugin~=1.5->-r requirements.txt (line 3)) (2.23.4)
Requirement already satisfied: typing-extensions>=4.6.1 in ./.venv/lib/python3.12/site-packages (from pydantic>=2.0->mkdocs-d2-plugin~=1.5->-r requirements.txt (line 3)) (4.12.2)
Requirement already satisfied: bracex>=2.1.1 in ./.venv/lib/python3.12/site-packages (from wcmatch>=7->mkdocs-awesome-pages-plugin~=2.9.3->-r requirements.txt (line 5)) (2.5)
Requirement already satisfied: six>=1.5 in ./.venv/lib/python3.12/site-packages (from python-dateutil>=2.8.1->ghp-import>=1.0->mkdocs~=1.6->-r requirements.txt (line 2)) (1.16.0)

> frontscope@0.3.0 prepare
> husky

up to date, audited 442 packages in 4s

121 packages are looking for funding
  run `npm fund` for details

6 vulnerabilities (2 moderate, 3 high, 1 critical)

To address issues that do not require attention, run:
  npm audit fix

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.
touch etc/npm_install_ran_at
npx vue-tsc --noEmit -p tsconfig.vitest.json --composite false
npx vite --config etc/vite.config.ts build
vite v5.3.3 building for production...
✓ 1199 modules transformed.
dist/index.html                                            1.03 kB │ gzip:   0.51 kB
dist/assets/Infinity-B0if1oYt.ttf                         20.22 kB
dist/assets/logo-DC67Vj_R.svg                             59.11 kB │ gzip:  16.77 kB
dist/assets/Inter-VariableFont_slnt_wght-Cl4AQHp9.ttf    804.61 kB
dist/assets/index-DFwbFjLi.css                            15.86 kB │ gzip:   3.41 kB
dist/assets/index-CzXZoO79.js                          2,057.94 kB │ gzip: 573.84 kB

(!) Some chunks are larger than 500 kB after minification. Consider:
- Using dynamic import() to code-split the application
- Use build.rollupOptions.output.manualChunks to improve chunking: https://rollupjs.org/configuration-options/#output-manualchunks
- Adjust chunk size limit for this warning via build.chunkSizeWarningLimit.
✓ built in 6.83s
node tools/pyrun.mjs mkdocs build --strict --config-file etc/mkdocs.yml
INFO    -  mkdocs-d2-plugin: Using cache at .cache/plugin/d2/db (dbm.gnu)
Error: executable 'd2' not found
make: *** [etc/Makefile:26: dist] Error 1
katestange commented 2 weeks ago

Ok, I installed d2 and it works. But aren't requirements supposed to happen automatically?

katestange commented 2 weeks ago

Ok, right now it compiles and serves, but the doc site is a blank white screen (in both firefox and chromium)?

gwhitney commented 2 weeks ago

Ok, I installed d2 and it works. But aren't requirements supposed to happen automatically?

Well, the difficulty is that d2 is neither a JavaScript package nor a Python package, and those are the only two languages we are set up to install packages for automatically. (It's written in the "Go" language.) So from the point of view of frontscope, it's an external dependency you have to install yourself, like git, make, node, or the python interpreter.

Ok, right now it compiles and serves, but the doc site is a blank white screen (in both firefox and chromium)?

The doc pages are only served with npm run doc:serve (doc pages only, live updates as you change the doc files) or npm run preview (both app and doc, but no live updates, you have to stop and re-run to see changes to the files). They are not served with npm run dev, because that just runs the TypeScript portion, i.e., the frontscope app. If either npm run doc:serve or npm run preview does not show the doc pages, let me know.

katestange commented 2 weeks ago

Yes, I'm referring to blank after npm run preview. The full HTML being served under preview is shown here. But npm run doc:serve works fine. Preview also worked fine last time I ran this PR (before recent commits). Screenshot from 2024-11-09 22-15-31

katestange commented 2 weeks ago

I believe visited links are a pale grey? I am seeing it maybe too pale on my screen - hard to read. Screenshot from 2024-11-09 22-18-31

gwhitney commented 2 weeks ago

Yes, I'm referring to blank after npm run preview.

Hmm, I can't reproduce. Try rm -r dist and then npm run preview again? When you click on the URL it shows (for me it is http://localhost:5050/) you should get the app, and then clicking on Documentation at the top right should give the doc site.

katestange commented 2 weeks ago

Try rm -r dist and then npm run preview again?

That worked! What's the explanation here?

gwhitney commented 2 weeks ago

I believe visited links are a pale grey? I am seeing it maybe too pale on my screen - hard to read.

Actually unvisited links. CSS mistake, should be fixed now, thanks.

gwhitney commented 2 weeks ago

Try rm -r dist and then npm run preview again?

That worked! What's the explanation here?

Well, dist is the directory the built files are written into. npm run build does not clean that out, it basically just presumes everything will get overwritten with the new stuff. But it can happen that some leftover file from a previous run, especially if there were errors in that run, can gum up the works. So when anything gets funny, I always just try blowing away all of dist -- which is always safe, since it can be regenerated easily -- and rebuilding.

katestange commented 2 weeks ago

the d2 flowcharts look great!

gwhitney commented 2 weeks ago

OK, I've responded to a number of your comments above, and implemented all of your suggestions that I didn't otherwise respond to. The biggest outstanding thing is how to incorporate in the frontscope ui links to the visualizer and sequence pages for the current visualizer and sequence of a specimen (issue #321).

katestange commented 2 weeks ago

I have a large-scale comment. The highest hierarchy level has sections "Extending" and "Contributing" and it's not clear to me what the difference between these two words/topics really is or should be? I think maybe to us it means "extending it on your own machine" vs. "checking in code to the project" but I don't think that's clear. Maybe Extending, Building a Visualizer, and Contributing should all be under a larger heading such as "Extending and Contributing", with sub-topics being named (in the same order) "Getting started", "Building a visualizer" and "Contributing your code". Or something similar?

gwhitney commented 2 weeks ago

I have a large-scale comment. The highest hierarchy level has sections "Extending" and "Contributing" and it's not clear to me what the difference between these two words/topics really is or should be? I think maybe to us it means "extending it on your own machine" vs. "checking in code to the project" but I don't think that's clear. Maybe Extending, Building a Visualizer, and Contributing should all be under a larger heading such as "Extending and Contributing", with sub-topics being named (in the same order) "Getting started", "Building a visualizer" and "Contributing your code". Or something similar?

Yes, right, those are the two different things: making Numberscope do something new, and submitting some new behavior for Numberscope for it to be considered to become part of the "official" version. To me they are very different sections for very different activities, and I think that is borne out by the content: the Extending part is about the code organization and design and how to code certain types of behaviors, while the Contributing part is about git and testing and PRs and the like -- the mechanics of shuffling code around, so to speak. So I'd recommend keeping them separate.

But I do get your point about "Building a Visualizer" being part of Extending -- it's not really at the same level in the hierarchy. There could just as well be a "Building a Sequence" section also under Extending. There just isn't because we don't really expect people to make new sequences.

I also get your point that to the uninitiated, the import of "extending" vs. "contributing" may not be clear.

So what about the following?

(A) Move "Building a visualizer" under "Extending", so that Extending has pages "Extending Numberscope", "Setting up to run from source" and subsection "Building a visualizer" with its three pages.

(B) Retitle "Extending" and "Contributing" to be more "plain English." One option that comes to mind for "Extending" would be "Developer Guide" in contrast to "User Guide" above it in the outline. But I could see a worry that this phrase "Developer Guide" is also jargon itself. So maybe "Making Numberscope do something new"? "Changing how Numberscope works"? "Adding to what Numberscope can do"? The last seems the clearest and simplest to me... And then for a new title for "Contributing," maybe just "Contributing your changes to Numberscope"? I mean the reason I think the term "Contributing" should be fairly clear is that it's been pretty widespread across many software projects for a long time now to have files README and CONTRIBUTING at the top level; it's a quasi-standard.

Anyhow, let me know your thoughts and if we reach consensus, I will make it so.

And I guess at this point we're just going to wait for the meeting to discuss which way to go for #321, although if you have comments on that feel free to post them. If you're leaning any certain way, I could do a trial implementation in time to look at together in the meeting, with no problems if we decide to go a totally different way. Doing proposal 4 took me about 20 minutes and led me to be pretty solidly against it, so that was worthwhile...

katestange commented 2 weeks ago

Anyhow, let me know your thoughts and if we reach consensus, I will make it so.

Your suggestions sound reasonable -- my only worry is if the section titles get so long that they have to wrap -- so see how it looks?

gwhitney commented 2 weeks ago

Auxiliary comment: in user_guide.md under Errors makes reference to an email in the popup... shouldn't the email just be given here?

The idea was to make the email not scrape-able by bots.

gwhitney commented 2 weeks ago

worry is if the section titles get so long

Yes, length is an issue. They don't wrap, they just disappear under the 'scope canvas. So I had to abbreviate Numberscope by 'scope in one place. Let me know what you think; happy to try other headings.

katestange commented 2 weeks ago

The idea was to make the email not scrape-able by bots.

It is linked directly on the About page. Is that a concern?

katestange commented 2 weeks ago

Yes, length is an issue. They don't wrap, they just disappear under the 'scope canvas. So I had to abbreviate Numberscope by 'scope in one place. Let me know what you think; happy to try other headings.

Ok, I like the structure now, and actually we could change "Adding to what the 'scope can do" to just "Extending the 'scope". I think that actually the two terms "Extending the 'scope" and "Contributing your changes" are worlds clearer than "Extending" and "Contributing". This is because they now imply two stages to something, where "contributing" is something you do AFTER you already have changes.

gwhitney commented 2 weeks ago

It is linked directly on the About page. Is that a concern?

So it is. And I gather that you have not experienced that email address being spammed. Would you like me to make a similar link in the user guide?

gwhitney commented 2 weeks ago

Ok, I like the structure now, and actually we could change "Adding to what the 'scope can do" to just "Extending the 'scope". I think that actually the two terms "Extending the 'scope" and "Contributing your changes" are worlds clearer than "Extending" and "Contributing". This is because they now imply two stages to something, where "contributing" is something you do AFTER you already have changes.

OK, will do, but "Extending the 'scope", "Extending Numberscope", "Adding to Numberscope" ...? Mostly just wondering, if we can go with something shorter, is there any reason to introduce the contraction "`scope" in a heading? It was sort of a desperation move on my part to make it fit..

gwhitney commented 2 weeks ago

So it is. And I gather that you have not experienced that email address being spammed. Would you like me to make a similar link in the user guide?

Oh, actually, that is in what to do if you encounter an error. The real thing to do is file an issue, not email us. I will change that in the next update.

katestange commented 2 weeks ago

OK, will do, but "Extending the 'scope", "Extending Numberscope", "Adding to Numberscope" ...? Mostly just wondering, if we can go with something shorter, is there any reason to introduce the contraction "`scope" in a heading? It was sort of a desperation move on my part to make it fit..

All seem fine to me. You're right, no reason to contract if not necessary. And yes, for errors if you'd rather they file an issue it should say that.

gwhitney commented 2 weeks ago

OK, there's a prototype for #321. It turns the rightmost item in the nav bar to "Help" which drops down to a Visualizer link, a Sequence link, and the prior Documentation link. Let me know your thoughts. (I likely still have to check in new CI snapshots, will do that shortly, but it shouldn't matter for trying out what I just pushed.)

gwhitney commented 2 weeks ago

OK, I think if we decide this new "Help" menu (basically #321 proposal 5, just with "about" on the logo instead of the "Help" menu) is generally the way to go, as opposed to any of proposals 1,2,3, or 6 from there or something else, here are some things we should do/think about doing:

Thanks for any other thoughts/guidance, or votes on whether in fact this Help menu is the way to go.

katestange commented 2 weeks ago
  • Speaking of appearance, what about the font of the "Help" dropdown? Is the top bar font too "flowery"/unreadable? Conversely, would switching to the main font in the dropdown be too jarring?

We could try the main font? Smaller but bolder would be more readable I think. Right now it is really quite thin/flowery. Maybe the dropdown needs a border too?

  • In the docsite part, currently "return to scope" is on the numberscope logo, so it's sort of a toggle between the docs (at least, it goes to the About page, which is in the docs) and the scope. Is that too undiscoverable? Should we do some/all of:

    • somehow style it differently to look more like toggle -- a button that pops in/out?
    • just add a redundant "Back to Numberscope" link on the right, where "Help" is in the 'scope?
    • Insert a (likely smaller) "Back to" before the numbescope logo in the top bar in the doc site?

We could just be redundant (so the second option here). Right now in the PR the docs has only "Gallery" at the right, and I think "The Scope" and "Gallery" might be ok here.

gwhitney commented 2 weeks ago

OK, I think I did all the things we discussed. Whaddaya think?

katestange commented 1 week ago

OK, I think I did all the things we discussed. Whaddaya think?

Looking nice! I like the tiny hint of a tree structure created visually. Tiny tweaks I'd suggest: the mouse should probably change to a finger point when it is over the word "Help", the underlining on the submenu items (like Turtle) extends too far right (should stay under the word only), and I might move the menu down a few pixels so it doesn't crowd the word "Help".

Also, I think maybe the sequence manual pages in the docs shouldn't have pictures of visualizers in action. It makes them look like visualizer manual pages, which for some reason I find confusing. Maybe we could give a screenshot of a formula entry box in action, and the OEIS website header.

gwhitney commented 1 week ago

Tiny tweaks I'd suggest: the mouse should probably change to a finger point when it is over the word "Help",

Check.

the underlining on the submenu items (like Turtle) extends too far right (should stay under the word only),

Check.

and I might move the menu down a few pixels so it doesn't crowd the word "Help".

I have moved it down as far as possible with the current layout. If I move it one pixel farther, the popup disappears as you move the mouse down to one of the menu items. That's because it is using the "hover" property to make itself visible, and if there is any gap between the Help html element and the popup, hover stops being true in the midst of your moving the mouse, and the popup goes away before you can get there. Is it far enough? If not, it's of course possible to get it to work lower, just it's more work because I would have to change the layout. Let me know.

Also, I think maybe the sequence manual pages in the docs shouldn't have pictures of visualizers in action. It makes them look like visualizer manual pages, which for some reason I find confusing. Maybe we could give a screenshot of a formula entry box in action, and the OEIS website header.

The easiest thing to do was just crop them down to only the sequence entry boxes. How's that look?

katestange commented 1 week ago

Misc comments:

(1) I like the way the formula user page image looks now. (2) I think the menu is ok where it is (we can ask Aaron), but has the header gotten thicker, or is that my imagination? (3) Now that gallery responds to mouseover with underlining, should the main Numberscope header respond the same way? (4) When I'm at the page for OEIS sequence, there's a little directory path at the top of the page. The house icon is a link, but the other words aren't. Should they be? For example, I tried to click there to go up to Sequences directory.

gwhitney commented 1 week ago

Misc comments:

(2) I think the menu is ok where it is (we can ask Aaron), but has the header gotten thicker, or is that my imagination?

Not sure what you mean, we can discuss shortly.

(3) Now that gallery responds to mouseover with underlining, should the main Numberscope header respond the same way?

The reason that the Numberscope logo/header on the left isn't underlining is that it is an image, not text. I think the Delft team said it didn't look so good as text (line weight off) so they touched it up as an image, or something like that. But before this PR, Gallery, About, and Documentation all underlined but the Numberscope logo didn't. So it's not really different. But if you think it should do something, we could either make its background turn "Numberscope blue" on hover, or we could generate an image of precisely the same pixel dimensions with the Numberscope word underlined, and swap them on hover. Let me know.

(4) When I'm at the page for OEIS sequence, there's a little directory path at the top of the page. The house icon is a link, but the other words aren't. Should they be? For example, I tried to click there to go up to Sequences directory.

The reason the other words aren't links is because the rightmost one is the current page, and there's no point in a page linking to itself, and the others are headings in the outline view on the left, but the way MkDocs generates pages, there are no pages corresponding to the headings. I.e., there is no "User Guide" or "User Guide / Sequences" page, just "User Guide / Introduction" and "User Guide / Sequences / Random", for example.

If the breadcrumbs (the usual term for the items in the directory path) not being links is really bothersome, there is an MkDocs plugin that lets you assign pages to the headers themselves, so for example instead of there being an "Introduction" page as the first item under "User Guide", that would be the "User Guide" page. Let me know if you want me to turn on that feature and rearrange the pages a bit, assigning some page to each of the outline headings. This plan might require writing some new short pages to be the landing page for "Visualizers" (i.e., an overview of visualizers in general), for example. Then it should be that the breadcrumbs will be links to those pages associated with the headers. Again, let me know.

gwhitney commented 1 week ago

Notes from meeting:

Diagram items:

UI items:

gwhitney commented 1 week ago

OK, I've struggled with the lifecycle diagram almost the entire time since the meeting. I have just pushed where I landed. After working with things like "parameter change" starting in midair, I realized what I was unable to articulate during the meeting that is lost if we do that (although I think Kate did more or less say it at one point): the actions that lead away from the draw loop disrupt the loop. The loop can't continue until the call path gets back around to it. On the other hand, mouse clicks, etc., do not disrupt the event loop. It will continue on its merry way unless you do something in the handler to disrupt it. So I thought it was important that canvas resize, parameter change, and sequence change all emanate from the draw loop.

To try to avoid the misleading aspect that Aaron raised, I changed the draw loop from a method box to an "other code section" entitled "p5 Draw Loop" that explains it calls the draw() method for you. Hopefully that clarifies the point that was worrying him.

I think the uniform color for each path through the methods is really helpful. It's reinforced by uniform text labels as well. I did leave out "init" between the constructor and individual parameter checks, because it eats vertical space (which is at a premium here) without adding any new information, even for a person who has difficulty distinguishing colors, since there is only one path there anyway. However, if you want that last "init" label in for utter consistency of the edge labels, let me know -- it's trivial to do.

Other than that or very minor tweaks/corrections that anyone may see, I am moving on from this diagram at this point. I've spent quite several days on it all told, and I think it is the clearest its been and that it adds a lot to the documentation, but I also think I have reached the point of diminishing returns on it. If anyone else wants to hack on it to try to improve it further, be my guest. But be warned: the layout is quite sensitive to the specification, and I have put in several dummy nodes for routing and spacing to get it to look as reasonable as it does.

gwhitney commented 1 week ago

OK, I just added #494 with the three planned enhancements to how OEIS search and IDs are handled and presented in numberscope, since as I was doing the implementation it seemed to me that those three things were all related to each other but had nothing to do with this PR, really.

The latest push should have implemented everything else we discussed, so I am marking this as ready for review. @katestange / @Vectornaut , have at it!