Consider adding README.md support to directories
Categories
(Webtools :: Searchfox, enhancement)
Tracking
(Not tracked)
People
(Reporter: gregtatum, Unassigned)
References
Details
GitHub has a very nice feature where it automatically displays a README.md file when it exists in a directory. This makes it really easy and straightforward to document the project, on a folder-by-folder basis. It also serves as an easy way to dump markdown in folder and have documentation checked in the tree without a build step. It would be really nice to have this support in Searchfox.
Here is an example in the Firefox Profiler where we leverage this feature:
https://github.com/firefox-devtools/profiler/tree/master/src
It would be great to be able to do the same practice when we're documenting the Gecko side of things as well.
|
||
Comment 1•5 years ago
|
||
It would be great if in addition one received a README.md preview popup when mousing over directories in the path links. This could allow one to get a quick overview without needing to navigate away from one's search results.
|
||
Comment 2•2 years ago
|
||
(In reply to Nico Grunbaum [:ng, @chew:mozilla.org] from comment #1)
It would be great if in addition one received a README.md preview popup when mousing over directories in the path links. This could allow one to get a quick overview without needing to navigate away from one's search results.
Can you elaborate on this use-case and its motivation a little more? We're getting close to being able to support functionalities like this and I want to stew on this a little. In particular, I think a hover pop-up is likely to be inconsistent with searchfox's existing UX and feedback from "fancy" branch experiments, but there's potential to treat the path bread-crumbs similarly to symbols for consistency and to be able to expose a variety of context menu options and then:
- Have a clicked on or hovered over symbol (and therefore directory path) show context in the speculative new "super sidebar" which is where I'm tentatively planning to throw all the extra context in order to avoid it being in the way of things in the immediate area of the cursor or consuming vertical space.
- The context menu would want to be terse but could only have "Go to README.md" and this could either be thresholded on a basic "is this a trivial README.md that's useless or is it something better" heuristic and/or include some quantifier about how much content appears to be in the readme.
The other context menu options that could be supported would be things like: "go to directory listing" (the existing single-click bheavior), "exclude everything under this directory" , "only include things under this directory", and maybe some revision-control related stuff like "show recent changes in this directory" (which could also include a quantifier).
|
|
||
Comment 3•1 year ago
|
||
(In reply to Andrew Sutherland [:asuth] (he/him) from comment #2)
(In reply to Nico Grunbaum [:ng, @chew:mozilla.org] from comment #1)
It would be great if in addition one received a README.md preview popup when mousing over directories in the path links. This could allow one to get a quick overview without needing to navigate away from one's search results.
Can you elaborate on this use-case and its motivation a little more? We're getting close to being able to support functionalities like this and I want to stew on this a little. In particular, I think a hover pop-up is likely to be inconsistent with searchfox's existing UX and feedback from "fancy" branch experiments, but there's potential to treat the path bread-crumbs similarly to symbols for consistency and to be able to expose a variety of context menu options and then:
- Have a clicked on or hovered over symbol (and therefore directory path) show context in the speculative new "super sidebar" which is where I'm tentatively planning to throw all the extra context in order to avoid it being in the way of things in the immediate area of the cursor or consuming vertical space.
- The context menu would want to be terse but could only have "Go to README.md" and this could either be thresholded on a basic "is this a trivial README.md that's useless or is it something better" heuristic and/or include some quantifier about how much content appears to be in the readme.
The other context menu options that could be supported would be things like: "go to directory listing" (the existing single-click bheavior), "exclude everything under this directory" , "only include things under this directory", and maybe some revision-control related stuff like "show recent changes in this directory" (which could also include a quantifier).
Apologies for not seeing this earlier. I find that whenever I need to navigate from the search results, there is some base chance that I will lose state if I need to navigate back. This can happen frequently because the context for a result is limited to a single line, which is often insufficient to tell if the result is relevant. A popup with a few lines more of context on mouse over would allow me to continuously scan down a list of results more effectively, without the worry of dropping positional state within the results list.
|
|
||
Comment 4•1 year ago
|
||
Thanks for the use-case context! You may a very good point about the navigation state change.
After I posted my own comment I realized that, of course, we do have a pop-up/hover interaction paradigm, and it's the blame/annotate-strip and it has an interaction paradigm for hover scrubbing as well as an accessibility idiom which is also a way to pin the contents. That is, the blame contents are displayed on hover or click/enter in the cell. But click also hides the blame pop-up, so there's a weird pattern where, if you're using the mouse as opposed to a screen reader, when you click on a blame cell, you will be hiding the blame pop-up, so it takes a second-click to make it sticky. However, I do think a double-click will make it stay as the events currently exist, although it will transiently disappear because we see it as 2 click events.
It would be a bit non-conventional, but we could mimic this by adding an additional "peek" column to the first (visual) column of the file listing table that looks like the blame strip that can be scrubbed over. This would keep the hover interaction out of the way of people using the table like a table, as well as ensuring that we have some serious screen real-estate to display the previews. This could also form the basis for experimenting with other interaction paradigms which could also be controlled via settings.
For the markdown preview, I figure we could render the inferred table of contents from the heading structure of the document, plus a non-trivial portion of the top of the document; enough to ensure that we fill up the max visual area we allocate. For things like C++ header/source files, we could mimic the TOC + contents 2-column model by dumping a ul/li-hiearchy of the symbols defined in the file, plus excerpted source listing contents where we effectively skip over mode-lines, license blurbs, pragma-once #ifndef equivalents, #includes, namespace declarations, and forwards. This would leave us with file-level block comments plus core definitions, ideally. Alternately we might just filter based on aggregation a line map from notable definitions plus their peekRange (which includes contents). We can iterate on this. Also, I'm pretty interested in maybe throwing in an automatic diagram of the control flow and/or ownership relationships of the contents of the file as long as it meets some minimum level of complexity; just having a bunch of boring scattered boxes wouldn't be helpful and would be likely to bias people against the automated diagrams.
|
|
||
Comment 5•1 year ago
|
||
Another good candidate for hover contents is of course actual blame data, so that people can see what changed in the file concisely. But that might also be the case where we could try and do something more explicitly inline in the table in response to clicking. Specifically:
- Add a new column "Recent Changes: Nightly, Beta, Release" which, for each file, contains the number of lines in the file that have changed on mozilla-central since we last branched beta off of nightly, that landed in the nightly phase that now is beta, and that landed in the nightly phase that now is release. This probably would want to be a sum of the lines removed and added in each patch that weren't part of a paired backout. In other words, backouts would be modeled as anti-commits which might be a separate metric like "churn".
- Also add a pretty decorative row divider visualization which is a basically a heat-map of the existence of the file and changes to it over time, although we might visually encode addition separately from removal. Since Firefox has explicit releases, the heat-map buckets probably would most sensibly correspond to specific version numbers. Note that this would entirely be from the perspective of mozilla-central and would not reflect any changes made on release branches.
- For an accessibility mapping, I think having the time-series of changes as dense information here would be quite valuable with appropriate decimation like we do for code coverage where, for example, a coverage cell for the value "19910" is simplified to "hit 19k". Since no-change is much more likely than changes, it would probably make sense to use an aria-label that labels the revisions rather than reading out long consecutive chains of nothing happening and making it hard to track version numbers. Also, visually the strong convention would be that time flows from left-to-right, but for screen-reader purposes, the time series absolutely would want to start with the most recent nightly changes and then move backwards in time to previous release numbers of firefox. I can presumably order the DOM from newest to oldest but use CSS to visually lay out the timeline from right-to-left.
- Clicking on the recent changes column could expand a hidden table row which would have a time-bounded list of recent commits, ignoring bounced landings. These would be hierarchically clustered ul/li-style by release number. There could be an up-sell at the end of the list to go to a history page for the given file that would be a new standard URL endpoint that would support git-hash based paging. (That is, all paging is accomplished by providing direct git revisions to start from rather than using a SQL-style LIMIT/OFFSET mechanism.)
- Clicking on a heatmap cell with the mouse or via role="button" would trigger a pop-up with the excerpted list of changes for that revision which could have an appropriate perma-link to the history page. Maybe this pop-up could have prev/next arrows to effectively page through the per-revision data, skipping empty cells versus activating a weird hover/scrub mode. I think these specific pop-ups would involve dynamic requests although the server could have already pre-computed the history data and it would just be slicing and dicing that.
This is a pretty ambitious new set of functionality here, so I'm going to defer asking for accessibility feedback from :Jamie at this time until I actually have the underlying data pipelines plumbed or in the process of being plumbed.
Description
•