Allow for a single-level version of this theme #90
Comments
|
Yes, I have been thinking about adding multiple layouts (more simple) layouts that you can choose from, but that can share common building blocks in this project. The alabaster-style single sidebar + in page TOC would become similar to a readthedocs+toc-sidebar from a layout point of view? (which would be useful to have!) Next to the Alabaster-style layout, some other layout ideas:
|
|
relevant to your gitbook comment, I'd love to use this theme for Jupyter Book (which draws inspiration heavily from GitBook). We are thinking about re-writing the backend for JupyterBook to use Sphinx, and in that case, it would be great if we used a theme that built off of a good foundation such as the pydata theme |
|
I was just experimenting with a customized version for a small package, to do something alabaster-like. This is the result for now: http://jorisvandenbossche.github.io/example-pandas-docs/contextily/index.html We should certainly make this even simpler, or actually include this as option in this package? |
|
Is this something that the sphinx-book-theme could be useful for as well? I think it acts well as a more "lightweight" version of the pydata theme: https://sphinx-book-theme.readthedocs.io/en/latest/ I have been trying to upstream as much as possible into pydata-sphinx-theme...I would be happy to find a way to make this more generally useful for the community (already it is designed to be pretty modular, and doesn't "depend" on Jupyter Book) |
|
I actually looked at sphinx-book-theme's code / layout as inspiration :) (I could actually also just have tried it out ..) My feeling says that something basic like this would be nice to simply include here. I don't know how well it works, though, to include multiple possible layouts in a single package / single theme. But is has been on my mind for a longer time (see also the older posts in this issue) to provide a configurable layout in this theme.
And thanks a lot for that, and sorry that I have not always been up to speed to review this |
|
Very concretely on this specific layout and jupyter-book-theme, some questions that come to my mind:
For example, I suppose the download button at the top is maybe something book-specific (and the printing css), or the in-content-sidebar, or ... So those are still add-ons that sphinx-book-theme could provide, even if more of the layout specific things would be included here? On the other hand, it's great that other packages start customizing this theme and depending on it, so it might also be fine to leaving it to another package to "specialize" in a different default layout. |
|
I agree with you there are probably things in there that aren't useful for a generic pydata-style website. I don't know that those are things that would be problems for people, they just might not be as useful. I agree with you that a "single page" version of this theme would be good as well...that's part of what #110 was setting the stage for. Maybe it is accomplishable by upstreaming more things from the sphinx-book-theme (e.g. the sidebar collapse animation?). I'd love to be able to have the |
|
Just another note here that I think the sphinx-book-theme has evolved nicely as a single-page version of this theme. We've started using it for some of our smaller documentation sites as well. E.g. here's the markdown-it-py docs:
(link: https://markdown-it-py.readthedocs.io/en/latest/) Throwing it out there to see if it could be used as a single-page alternative to this theme. There is still some upstreaming I want to do for the If there are some awkward "book-like" features in there that don't make sense for a single-page docs site, I'd be friendly to removing them as defaults and having them configurable for people that want a book-like layout |
|
A lot of similar issues like #146, in addition to those mentioning this issue above. Can they be consolidated? |
|
We are now advertising Furo and sphinx-book for single-level documentation in |
|
IMO we could just close this and refer to the other theme options that are out there (probably in particular the book theme, since it builds heavily on this theme's structure and style). My feeling is that we should focus our efforts on making this a great three-column layout theme, rather than trying to accommodate many different layouts. I'll hold off on closing this to see if others object though! |
12rambau
added
the
needs: discussion
|
We are building the CWL User Guide with this theme, and at the moment we have the same issue, where our landing page has a blank/empty space in our sidebar. The search is useful (although I wouldn't mind if it was moved to the top bar as mentioned in linked discussions), but having our table of contents rendered on the left-sidebar would be better for us. For now, I found the simplest way to achieve this—after looking at @choldgraf's example in #536 (thanks!)—to just pass the
No matter the level the user is reading, the sidebar now displays the complete TOC from level
Thanks! |
|
A simple but cheesy work around I have is to add on the index page <meta http-equiv="refresh" content="0; url=all/index.html">This will automatically redirect users to the nested docs |
Thank you all for your workarounds! As mentioned above, having the 2 behaviours within the theme would be too complicated so I'll close this issue. |
12rambau
added
wontfix
and removed
needs: discussion
This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit circumvents upstream theme issues pydata/pydata-sphinx-theme#90 and pydata/pydata-sphinx-theme#221 with the "standard" `_templates/sidebar-nav-bs.html` hack shamelessly copy-pasted into literally *every* project requiring that theme. This includes @beartype, because why not spew boilerplate that nobody understands everywhere? (*Intimate intimations of illegitimate legerdemain!*)
This commit is the next in a commit chain coercing our monolithic `README.rst` documentation onto Read the Docs (RTD), en-route to resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). Specifically, this commit circumvents upstream theme issues pydata/pydata-sphinx-theme#90, pydata/pydata-sphinx-theme#221, and pydata/pydata-sphinx-theme#1181 with the "standard" `_templates/sidebar-nav-bs.html` hack shamelessly copy-pasted into literally *every* project requiring that theme. This includes @beartype, because why not spew boilerplate that nobody understands everywhere? Sadly, doing so now requires pinning to a maximum obsolete version of this theme that will also surely die soon. And this is why I facepalm. (*Illogical ontological topology!*)
This minor release delivers pulse-quickening support for **pandera (pandas) type hints,** **PEP 484,** **PEP 585**, **PEP 591**, **PEP 647**, **PEP 3119**, and **pseudo-callables.** This minor release resolves **12 issues** and merges **2 pull requests.** But first, a quiet word from our wondrous sponsors. They are monocled QA wizards who serve justice while crushing bugs for humanity. High fives, please! ## Beartype Sponsors * [**ZeroGuard:** The Modern Threat Hunting Platform](https://zeroguard.com). *All the signals, All the time.* Thunderous applause echoes through the cavernous confines of the Bear Den. 👏 🐻❄️ 👏 And now... the moment we've waited for. A heinous display of plaintext that assaults all five senses simultaneously. ## Compatibility Added * **Pandera (pandas) type hints** (i.e., ad-hoc PEP-noncompliant type hints validating pandas `DataFrame` objects, produced by subscripting factories published by the `pandera.typing` subpackage and validated *only* by user-defined callables decorated by the ad-hoc PEP-noncompliant `@pandera.check_types` runtime type-checking decorator), resolving feature request #227 kindly submitted by @ulfaslakprecis (Ulf Aslak) the Big Boss Typer. @beartype now: * Transparently supports pandera's PEP-noncompliant `@pandera.check_types` decorator for deeply runtime type-checking arbitrary pandas objects. * *Always* performs a rudimentary `O(1)` `isinstance()`-based type-check for each Pandera type hint. Doing so substantially improves usability in common use cases, including: * Callables annotated by one or more pandera type hints that are correctly decorated by @beartype but incorrectly *not* decorated by the pandera-specific `@pandera.check_types` decorator. * (Data)classes annotated by one or more pandera type hints. * Pandera type hints passed as the second argument to statement-level @beartype type-checkers – including: * `beartype.door.is_bearable()`. * `beartype.door.die_if_unbearable()`. * Implements a non-trivial trie data structure to efficiently detect all type hints produced by subscriptable factories in the `pandera.typing` submodule. Let us pretend this never happened, @ulfaslakprecis. * **PEP 484- and 585-compliant generator constraints.** This release relaxes prior constraints erroneously imposed by @beartype prohibiting both asynchronous and synchronous generator callables from being annotated as returning unsubscripted standard abstract base classes (ABCs) defined by the `collections.abc` module. Now, @beartype permits: * Asynchronous generator callables to be annotated as returning the unsubscripted `collections.abc.AsyncGenerator` type. * Synchronous generator callables to be annotated as returning the unsubscripted `collections.abc.Generator` type. * **PEP 591** (i.e., `typing.Final[...]` type hints), partially resolving issue #223 kindly submitted by the acronym known only as @JWCS (Jude). @beartype now trivially reduces *all* `typing.Final[{hint}]` type hints to merely `{hint}` (e.g., `typing.Final[int]` to `int`). In other words, @beartype no longer raises exceptions when confronted with final type hints and instead at least tries to do the right thing. This still isn't *quite* what everyone wants @beartype to do here; ideally, @beartype should also raise exceptions on detecting attempts to redefine instance and class variables annotated as `Final[...]`. Doing so is *definitely* feasible and exactly what @beartype should *eventually* do – but also non-trivial, because whatever @beartype *eventually* does needs to preserve compatibility with all implementations of the `@dataclass` decorator across all versions of Python now and forever. Cue that head-throbbing migraine. It's comin'! Oh, I can feel it! * **PEP 647** (i.e., `typing.TypeGuard[...] type hints`), resolving feature request #221 kindly submitted by Google X researcher extraordinaire @patrick-kidger. @beartype now trivially reduces *all* `typing.TypeGuard[...]` type hints to the builtin `bool` type. ## Compatibility Improved * **PEP 3119.** @beartype now detects both **non-isinstanceable classes** (i.e., classes whose metaclasses define PEP 3119-compliant `__instancecheck__()` dunder methods unconditionally raising `TypeError` exceptions) and **non-issubclassable classes** (i.e., classes whose metaclasses define PEP 3119-compliant `__subclasscheck__()` dunder methods unconditionally raising `TypeError` exceptions) more narrowly for safety, resolving issue #220 kindly submitted by *ex*traordinary Google X researcher @patrick-kidger (Patrick Kidger). Notably, @beartype now *only* accepts `TypeError` exceptions as connoting non-isinstanceability and non-issubclassability. Previously, @beartype broadly treated any class raising any exception whatsoever when passed as the second parameter to `isinstance()` and `issubclass()` as non-isinstanceable and non-issubclassable. Sadly, doing so erroneously raises false positives for isinstanceable and issubclassable metaclasses that have yet to be fully "initialized" at the early time the `@beartype` decorator performs this detection. ## Features Added * **Pseudo-callable monkey-patching support.** `@beartype` now supports **pseudo-callables** (i.e., otherwise uncallable objects masquerading as callable by defining the `__call__()` dunder method), resolving feature request #211 kindly submitted by Google X typing guru @patrick-kidger (Patrick Kidger). When passed a pseudo-callable whose `__call__()` method is annotated by one or more type hints, `@beartype` runtime type-checks that method in the standard way. ## Documentation Revised * **Literally everything,** also known as the release that migrated `README.rst` -> [Read the Docs (RtD)](https://beartype.readthedocs.io), resolving both issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell) and ancient issue #8 kindly submitted by @felix-hilden (AKA the Finnish computer vision art genius that really made all of this possible). Readable documentation slowly emerges from the primordial soup of @beartype's shameless past for which we cannot be blamed. @leycec was young and "spirited" back then. Specifically, this release: * Coerces our prior monolithic slab of unreadable `README.rst` documentation into a website graciously hosted by Read the Docs (RtD) subdividing that prior documentation into well-structured pages, resolving issue #203 kindly submitted by @LittleBigGene (AKA the dynamo of the cell). * Documents *most* previously undocumented public APIs in the @beartype codebase. Although a handful of public APIs remain undocumented (notably, the `beartype.peps` submodule), these undocumented APIs are assumed to either be sufficiently unpopular or non-useful to warrant investing additional scarce resources here. * Updates our installation instructions to note @beartype's recent availability as official packages in the official package repositories of various Linux distributions. Truly, this can only be the final mark of pride. These include: * Gentoo Linux's Portage tree. * Arch Linux's Arch User Repository (AUR). * Improves the Python code sample embedded in the ["Are We on the Worst Timeline?" subsection of our **Beartype Errors** chapter](https://beartype.readthedocs.io/en/latest/api_roar/#are-we-on-the-worst-timeline). Thanks to @JWCS for their related pull request (PR) #210, which strongly inspired this bald-faced improvement to the usability of our `beartype.typing` API. * Circumvents multiple long-standing upstream issues in the PyData Sphinx theme regarding empty left sidebars via the requisite `_templates/sidebar-nav-bs.html` template hack shamelessly copy-pasted into literally *every* project requiring this theme. This includes @beartype, because why not spew boilerplate that nobody understands everywhere? Sadly, doing so requires pinning to a maximum obsolete version of this theme that will surely die soon. And this is why I facepalm. These issues include: * pydata/pydata-sphinx-theme#90. * pydata/pydata-sphinx-theme#221. * pydata/pydata-sphinx-theme#1181. * Truncates our `README.rst` documentation to a placeholder stub that just directs everyone to RtD instead. * Improves `linecache` integration commentary. Specifically, a pull request by @faangbait (AKA the little-known third member of Daft Punk) improves internal commentary in our private `beartype._util.func.utilfuncmake.make_func()` factory function responsible for dynamically synthesizing new in-memory functions on-the-fly. Our suspicious usage of `None` as the second item of tuples added as values to the standard `linecache.cache` global dictionary has now been documented. Thanks so much for this stupendous contribution, @faangbait! ## Tests Improved * **Mypy integration.** This release improves our `test_pep561_mypy()` integration test to intentionally ignore unhelpful non-fatal warnings improperly emitted by mypy (which encourage usage of `typing_extensions`, oddly enough). * **Sphinx integration.** This release resolves multiple intersecting issues involving integration testing of Sphinx + @beartype, including: * `test_beartype_in_sphinx()` h0tfix is h0t. This release generalizes our test-specific `test_beartype_in_sphinx()` integration test to support arbitrary versions of Sphinx, resolving issue #209 kindly submitted by @danigm the sun-loving Málaga resident who frolics in the sea that Canadians everywhere are openly jealous of. Specifically, this release fundamentally refactors this integration test to fork a new Python interpreter as a subprocess of the current `pytest` process running the `sphinx-build` command. * A Python 3.7-specific failure in our continuous integration (CI) workflow caused by Sphinx attempting to call deprecated functionality of the third-party `pkg_resources` package. This release simply avoids installing Sphinx entirely under Python 3.7; although admittedly crude, it's unclear how else @beartype could possibly resolve this. Since Python 3.7 has almost hit its official End-Of-Life (EOL) and thus increasingly poses a security concern, this is hardly the worst resolution ever. Really! Believe what we're saying. Break nothing! It's the @beartype way. This is why @leycec cries like a mewling cat with no milk. (*Thrilling chills spill towards an untoward ontology!*)
For a few projects that I'm using, I'd like to use this project for its simplicity, style, and modernity. However, our documentation isn't complex enough that it warrants a topbar with sections. We really only need an alabaster-style single sidebar that behaves sensible (with an in-page TOC to the right).
I wonder if we could set up the templates such that we could easily swap between a "multi-level" and "single-level" approach
The text was updated successfully, but these errors were encountered: