Add support for `CollapsedDocStrings` in `@meta` block #2394

goerz · 2024-01-08T03:51:58Z

Setting DocStringsCollapsed = true in the @meta block of a particular page essentially clicks the "Collapse all docstrings" in the navigation bar after the page loads, collapsing all docstrings on that page.

I think the approach of just having JavaScript click the collapse button is the right one here: First, I'm not sure that it would be possible to write out the page in a collapsed state, or at least not without doing some pretty gnarly rewrites of the HTMLWriter. More importantly, rendering the page expanded and then collapsing it with JavaScript seems like the right thing to do from an accessibility standpoint: We'd want the page to still be useful without JavaScript. I've been known to access API documentation in the terminal with w3m, so not relying on JavaScript to render the core content is something I actually care about. Screenreaders probably also wouldn't like if all docstrings initially rendered as hidden.

Closes #2282

goerz · 2024-01-08T04:04:39Z

With respect to #2282, this PR does not implement a global flag for collapsing all docstrings. It's not something I'm interested in, although it wouldn't be terribly hard to add it in (but definitely more work to document and test)

src/html/HTMLWriter.jl

goerz · 2024-01-15T18:44:35Z

I added collapse-by-default to the Internal API pages, e.g., https://documenter.juliadocs.org/previews/PR2394/lib/internals/anchors/

Interestingly (and unlike in my previous local testing), I'm finding that it doesn't seem completely reliable. Maybe I'll have to revise the JS a bit. It might be running too early or something.

mortenpi · 2024-01-15T23:37:27Z

One other thing: I'm a little bit skeptical of putting too many writer-specific options into the top-level scope of an at-meta block. Should we have some way to namespace writer-specific options like this? Not sure what the best syntax would be, but maybe something like:

Writer.HTML = begin
    CollapsedDocStrings = true
end

goerz · 2024-01-16T03:07:20Z

I'm a little bit skeptical of putting too many writer-specific options into the top-level scope of an at-meta block.

I have no strong feelings on this either way. Although I'd probably keep it flat, mostly because EditURL, Description, and maybe Draft would also seem to belong with Writer.HTML, but moving them is probably breaking compatibility.

Assuming I can make get the CollapsedDocStrings to work reliably at all, maybe we can mark it as "experimental" and then move it to a namespaced scheme afterward, in a separate PR.

goerz · 2024-01-23T20:32:40Z

assets/html/js/metadata.js

+let meta = $("div[data-docstringscollapsed]").data();
+
+if (meta.docstringscollapsed) {
+  $("#documenter-article-toggle-button").click();


This seems fine to me. It still shows the close-animation after the page is loaded. I don't mind it that much, but @mortenpi might still prefer if we speed it up.

@Hetarth02 Do you know what to add to control the animation speed?

I think I figured it out: e5b84d3

The currently deployed preview documentation disables the animation completely. Better? I'm okay with either.

goerz · 2024-01-23T20:33:13Z

docs/src/showcase.md

-| `A`    |      ✓      |      10.00 |
-| `BB`   |      ✓      | 1000000.00 |
+| object | implemented | value      |
+| ------ | ----------- | ---------- |


Seems a little unrelated to the PR, but I just kept it in

goerz · 2024-01-23T20:36:18Z

Okay, this is back on track now, and could be merged in principle.

We can still tweak this, of course, ~~maybe changing the animation speed, but that's optional as far as I'm concerned~~ (edit: done).

As before, https://documenter.juliadocs.org/previews/PR2394/lib/internals/anchors/ (and the other "internals" pages) demo the feature.

docs/src/man/syntax.md

mortenpi · 2024-01-30T21:03:44Z

assets/html/js/metadata.js

+let meta = $("div[data-docstringscollapsed]").data();
+
+if (meta.docstringscollapsed) {
+  $("#documenter-article-toggle-button").trigger({
+    type: "click",
+    noToggleAnimation: true,
+  });
+}


This whole thing probably needs to be in a $(document).ready(function () { ... }?

Let's try it! https://documenter.juliadocs.org/previews/PR2394/ should now have that change. Of course, all I can say is that it continues to work for me, so you'll have to let us know :-)

Squashed from https://github.com/Hetarth02/Documenter.jl/tree/Draft-PR-2394

I don't think the "Showcase" page is a good place to have all docstrings collapsed, as it only has a few interspersed docstrings, and the main text explicitly references features from within the docstring. The "Internals" pages seem more sensible, so I'm only leaving those.

mortenpi · 2024-01-31T09:41:51Z

With the fixes, it looks like it works now! @Hetarth02, are you still seeing the mobile search/sidebar issue you mentioned on Slack?

Hetarth02 · 2024-01-31T10:02:40Z

@mortenpi I just checked, everything seems to be working fine.

mortenpi

@goerz I took the liberty of pushing a DocStringsCollapsed -> CollapsedDocString bikeshed. Happy to revert it if you prefer DocStringsCollapsed. From my side, I'm happy if we merge this!

goerz · 2024-02-03T10:31:43Z

I have no preferences on the name of the option. Looks good to me!

mortenpi · 2024-02-04T23:36:13Z

Then let's merge it! Thank you @goerz and @Hetarth02 for iterating on this!

lmiq · 2024-02-22T20:18:58Z

I'm sorry. How is this keyword supposed to be used? Searching the Documenter docs leads me to the release notes page, than to these PRs, but there is not (as far as I could find) documentation on how to use these options.

goerz · 2024-02-22T20:23:06Z

Are you using the master branch version of Documenter? Because this has not been released yet.

If yes, then the relevant documentation would be here: https://documenter.juliadocs.org/dev/man/syntax/#@meta-block and an example is here: https://github.com/JuliaDocs/Documenter.jl/blob/master/docs/src/lib/internals/anchors.md (raw)

lmiq · 2024-02-23T00:26:37Z

Uhm, this in the release notes of 1.0.0, so that got me confused:

Added the ability to expand/collapse individual as well as all docstrings. (#1393, #2078)

goerz · 2024-02-23T01:55:36Z

That’s referring to the feature of being able to collapse and expand docstrings manually

goerz force-pushed the mg/meta-docstrings-collapsed branch from 0af4abd to f92cf71 Compare January 8, 2024 03:54

goerz added the Type: Feature label Jan 8, 2024

goerz mentioned this pull request Jan 8, 2024

Add keyword argument for folding all docstrings by default #2282

Closed

goerz changed the title ~~Add support DocStringsCollapsed in @meta block~~ Add support for DocStringsCollapsed in @meta block Jan 8, 2024

goerz mentioned this pull request Jan 8, 2024

On-hover footnote preview #2080

Open

goerz force-pushed the mg/meta-docstrings-collapsed branch from f92cf71 to 0e034e5 Compare January 9, 2024 21:17

mortenpi reviewed Jan 15, 2024

View reviewed changes

src/html/HTMLWriter.jl Outdated Show resolved Hide resolved

goerz force-pushed the mg/meta-docstrings-collapsed branch from 0e034e5 to cd9d476 Compare January 15, 2024 18:09

goerz force-pushed the mg/meta-docstrings-collapsed branch 2 times, most recently from 50b7c83 to 36d7d33 Compare January 15, 2024 21:06

goerz marked this pull request as draft January 15, 2024 21:41

goerz force-pushed the mg/meta-docstrings-collapsed branch 2 times, most recently from 326fe8e to 964f67e Compare January 15, 2024 22:02

goerz force-pushed the mg/meta-docstrings-collapsed branch 4 times, most recently from 12e0888 to 2768fac Compare January 16, 2024 02:40

Hetarth02 mentioned this pull request Jan 23, 2024

Draft pr 2394 #2421

Closed

goerz force-pushed the mg/meta-docstrings-collapsed branch 3 times, most recently from 9d34fcb to c303d45 Compare January 23, 2024 20:07

goerz commented Jan 23, 2024

View reviewed changes

goerz marked this pull request as ready for review January 23, 2024 20:34

goerz commented Jan 23, 2024

View reviewed changes

docs/src/man/syntax.md Outdated Show resolved Hide resolved

goerz force-pushed the mg/meta-docstrings-collapsed branch from 4132356 to 8999adb Compare January 24, 2024 02:35

mortenpi reviewed Jan 30, 2024

View reviewed changes

Hetarth02 and others added 8 commits January 31, 2024 00:07

Add support for DocStringsCollapsed in @meta block

a038ff4

Squashed from https://github.com/Hetarth02/Documenter.jl/tree/Draft-PR-2394

Collapse all Internal API docs by default

b4cac2a

Add test for data-docstringscollapsed="true"

66f0687

Whitelist DocStringsCollapsed in @meta block

7e42435

Update CHANGELOG

36cb788

Add documentation

5033afe

Remove the toggle animation

b4ba3a7

goerz force-pushed the mg/meta-docstrings-collapsed branch from 6cff39e to 9f93420 Compare January 31, 2024 05:10

Wrap in $(document).ready(function () {…}

4be8288

goerz force-pushed the mg/meta-docstrings-collapsed branch from 9f93420 to 4be8288 Compare January 31, 2024 05:15

mortenpi and others added 2 commits February 3, 2024 20:45

Update docs/src/man/syntax.md

fe30a8e

bikeshed: DocStringsCollapsed -> CollapsedDocStrings

44d9b15

mortenpi changed the title ~~Add support for DocStringsCollapsed in @meta block~~ Add support for CollapsedDocStrings in @meta block Feb 3, 2024

mortenpi approved these changes Feb 3, 2024

View reviewed changes

Merge branch 'master' into mg/meta-docstrings-collapsed

01fe970

mortenpi enabled auto-merge (squash) February 4, 2024 23:35

mortenpi merged commit 008ed3a into master Feb 4, 2024
18 of 22 checks passed

mortenpi deleted the mg/meta-docstrings-collapsed branch February 4, 2024 23:41

goerz mentioned this pull request Mar 4, 2024

Loading user assets before requirejs #2472

Open

goerz mentioned this pull request Mar 26, 2024

Links to collapsed pages end up off-screen #2485

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add support for `CollapsedDocStrings` in `@meta` block #2394

Add support for `CollapsedDocStrings` in `@meta` block #2394

goerz commented Jan 8, 2024

goerz commented Jan 8, 2024

goerz commented Jan 15, 2024

mortenpi commented Jan 15, 2024

goerz commented Jan 16, 2024

goerz Jan 23, 2024

goerz Jan 24, 2024

goerz Jan 23, 2024

goerz commented Jan 23, 2024 •

edited

Loading

mortenpi Jan 30, 2024

goerz Jan 31, 2024 •

edited

Loading

mortenpi commented Jan 31, 2024

Hetarth02 commented Jan 31, 2024

mortenpi left a comment

goerz commented Feb 3, 2024

mortenpi commented Feb 4, 2024

lmiq commented Feb 22, 2024

goerz commented Feb 22, 2024 •

edited

Loading

lmiq commented Feb 23, 2024 •

edited

Loading

goerz commented Feb 23, 2024

Add support for CollapsedDocStrings in @meta block #2394

Add support for CollapsedDocStrings in @meta block #2394

Conversation

goerz commented Jan 8, 2024

goerz commented Jan 8, 2024

goerz commented Jan 15, 2024

mortenpi commented Jan 15, 2024

goerz commented Jan 16, 2024

goerz Jan 23, 2024

Choose a reason for hiding this comment

goerz Jan 24, 2024

Choose a reason for hiding this comment

goerz Jan 23, 2024

Choose a reason for hiding this comment

goerz commented Jan 23, 2024 • edited Loading

mortenpi Jan 30, 2024

Choose a reason for hiding this comment

goerz Jan 31, 2024 • edited Loading

Choose a reason for hiding this comment

mortenpi commented Jan 31, 2024

Hetarth02 commented Jan 31, 2024

mortenpi left a comment

Choose a reason for hiding this comment

goerz commented Feb 3, 2024

mortenpi commented Feb 4, 2024

lmiq commented Feb 22, 2024

goerz commented Feb 22, 2024 • edited Loading

lmiq commented Feb 23, 2024 • edited Loading

goerz commented Feb 23, 2024

Add support for `CollapsedDocStrings` in `@meta` block #2394

Add support for `CollapsedDocStrings` in `@meta` block #2394

goerz commented Jan 23, 2024 •

edited

Loading

goerz Jan 31, 2024 •

edited

Loading

goerz commented Feb 22, 2024 •

edited

Loading

lmiq commented Feb 23, 2024 •

edited

Loading