docs: merge new docs into main #1776
Conversation
* Docs: add simpler "what-is-an-awkward-array" Fix: add dependency for ipyleaflet * Docs: add beginners guide (WIP) * Docs: mvoe user-guide under "fundamentals" Fix: use entries * Docs: add pydata-like index page We don't directly copy the pydata theme, namely: - we use sphinx-design, which is the replacement for the deprecated sphinx-panels - we use fontawesome for the icons instead of the pydata icons. This solves the question of freedom fo use, and dark-light support is free. ... * Docs: simplify api-reference Move "awkward array is..." to "what-is-an-awkward-array" * Docs: shorten index blurb * CI: build for RTD * Docs: use captions to group user-guide sections * Docs: insert ToC into index pages * Docs: add edit button * Docs: don't collapse navigation * Chore: use jsdelivr instead of unpkg * Docs: remove badges, add link to what-is-an-awkward-array * Docs: remove C++ reference from navbar * Docs: add release notes to navbar * Fix: remove local comment * Docs: add card for C++ reference Move the C++ reference URL to top as a clickable card. * Chore: rearrange static files for simplicity * Docs: correct `keys` → `fields` * Docs: move API reference to MyST * Docs: use intersphinx, use py domain * Chore: move docs into reference/ This makes it clear within the URL scheme that we're looking at an API reference It also ensures that we have a cleaner file-layout * WIP: remove <h2> from generated docs * Docs: don't wrap self in paren * Docs: don't include changelog in reference toctree * Docs: split changelog into separate page * Fix: generate kernels into new `generated` directory * CI: build docs for `docs` branch * Fix: ensure release/ exists * Docs: use `:class:` for classes * Docs: improve intersphinx / domain references * Docs: convert more :doc: roles * Docs: nest all class methods in curated docs * Docs: use ToC for create/convert * Fix: Doxygen links * Fix: link to kernel documentation * Fix: link to C++ docs * Chore: fix noxfile few recent docs Now we don't have a `docs` folder (and haven't for some time) this change updates the noxfile to build only the integrated Sphinx docs * Docs: remove caption for user guide, rename beginners guide * Docs: initial work on getting started * Docs: add introduction to user guide * WIP: initial paragraph explaining tutorial * Docs: use single-column card layout for small screens * Fix: remove duplicate images * Chore: remove _config.yml * WIP: work on "overview" * Chore: revert 7374959 and friends We can revisit this later once machinery is in place * WIP: clean-up title cases to title-case * WIP: Work on tutorial content * Docs: extend getting started * Fix: include contributor guide in ToC * Docs: lowercase titles * Chore: remove unused file * Docs: convert to sentence case
* CI: run on pull-requests of docs Upload only HTML * CI: improve job comments * CI: build docs whenever docs-sphinx/ changes * CI: only unpack pre-built docs on RTD * Fix: ensure target directory exists
* Docs: add comment to self * Fix: ignore release contents * CI: run on any PR
* Chore: preserve release/ directory * Chore: use Python 3.10 * CI: quote yaml * Fix: `metadata_from_parquet` now returns a dict
|
No, this is new since I last looked. Cool! It's exactly the point (b) I was describing: so that part is done. Point (a) is something we just need to wait for, so this is as ready as we can make it. I vote for the 3 badges + 1 "Try it!" badge that goes to this "What is an Awkward Array?" page. |
|
I've added a "Try It" in the form of a |
|
Currently Sphinx is not generating a primary sidebar for the API-reference children. Investigating. |
Sphinx was finding the toctree twice, I believe.
|
@jpivarski this is ready to go in my view. I haven't solved the |
There was a problem hiding this comment.
It looks pretty good on a phone, too: http://mobiletest.me/iphone_5_emulator/?u=https://awkward-array.readthedocs.io/en/docs/index.html
(Though the badges/buttons could have a top or bottom margin to not be stuck together when the window gets very narrow.)
When I ran the "Try it in your browser" in the simulated phone first and then later in a regular browser tab, the piplite.install("awkward") line failed with
File /lib/python3.10/site-packages/micropip/_micropip.py:177, in WheelInfo.validate(self)
175 sha256_actual = _generate_package_hash(self.data)
176 if sha256_actual != sha256_expected:
--> 177 raise ValueError("Contents don't match hash")
ValueError: Contents don't match hash
but I'm guessing that it's related to the mobile test. Reloading fixed it. (This page might need to accumulate some hints, like trying "Run → Run All Cells" and reloading if there are any problems. It's nice to see that reloading restores the original state, but a visitor might want to know that would happen, so they don't write too much code in this notebook without saving it.
It would be nicer if the JupyterLite scaled with the available space, but I know that's asking for a lot. It probably isn't possible.
Leaving the "Try it in your browser" page makes Chrome say that work may be lost. It would be ideal to get rid of that message (we've already decided that deleting data upon reload is the policy), but, failing that, it could be one of the messages on the page.
We want to keep those messages at a minimum, but:
- To run the code, click on the first cell (gray box) and type shift-enter through the cells.
- Or select "Run All Cells" from the "Run" menu.
- Feel free to experiment, but if you need to restore the original code, reload this browser page. Any changes you make will be lost when you reload!
- When you leave the page, you might get a "Changes you made may not be saved" message, which you can ignore.
I really like how the front page of the User Guide has all of the contents expanded out. That facilitates immediately jumping to a sub-section without having to know which section it's hidden in, but the left-bar can remain collapsed by default.
I really, really like the API reference.
It's odd to have any ak.* functions after the "Low-level layouts" section. For instance,
- "Converting between backends": arguably low-level, may belong here
- "Indexing and grouping": these are high-level functions that impact the high-level view (i.e. you don't need to know about layouts to have reason to use these functions)
- "Copying and packing arrays": arguably low-level, though someone working at a high-level may really appreciate
ak.packed.
The "Additional documentation" can just be removed; the diagram is wrong and it's not serving a purpose anymore.
Putting the AwkwardForth documentation last is good, though we also need the kernel documentation, which should be the very last. That kernel documentation (currently not generated) has more information than can be found in the C++ API reference because it comes from the kernel-specification.yml.
The nested sections in the AwkwardForth documentation and, to a much greater degree, the kernel documentation would flood the front page of the API reference if they were included. These two, at the end, can be an exception to the inlining of nested sections in reference/index.html.
I like how you have the "C++ documentation" called out in a box at the end, but at the end. With "Additional documentation" gone, it would be the last thing on reference/index.html.
That's it! This is all very nice. My new requests don't have to be part of this PR; you can merge docs into main and I'll bulletize them and make them an issue-request.
We could add a custom styling to this - the current iframe is set 600px, but we could do something more dynamic to constrain it between sensible defaults.
We can actually save the notebook; I went to pains to disable this. I couldn't find a satisfactory way to clear the caches reliably (it should just be "Clear site data", so maybe I'm missing something obvious), so I disabled the storage backend.
This is annoying; there's a serviceworker involved and I think it's caching the old wheel sometimes. Refreshing the page does seem to fix it. |
It's appreciated! We don't want it to look like the tutorial is broken because a visitor has a non-standard version of it in their browser cache. That ought to be a common use-case for JupyterLite. |
Right, that was my worry - even I found myself confused sometimes, and I was midway through introducing it 🤣 |
|
I'm keeping this branch open so that we can preview it on RTD :) The idea is now that we'd target |
This PR merges the new docs (#1552, #1563, #1590, #1591, #1592, #1594, #1630, #1734) into
main.As discussed elsewhere, these aren't finished v2 docs. But, they lay the groundwork for us to start iterating. #1575 will eventually target
main, and fill out missing sections, in addition to the comments raised by @jpivarski in #1734By merging into
main, however, we can avoid needing to keep these two branches in sync!