Docs: Reorganize reference v2 #7159

NickCrews · 2023-09-14T23:22:53Z

This is a followup per #7141

Move every datatype-specific API out of the top-level section. eg ibis.array() got moved to collections section
Now only backend-specific stuff got left in the top-level section. Therefore, I renamed it to "Connections API".

In addition to these high-level changes, also a few tweaks:

soft deprecate ibis.where
fix ibis.ifelse docstring (plenty other functions like this are still missing docstrings, but at least the existing ones should be correct)
import ibis in a doctest to prevent a rendering failure. This was little weird. This wasn't failing before only due to the ordering of this function in the larger API tab. All of the members in a a quartodoc section get squashed into a single .qmd file. Then quarto goes through and evaluates all the docstrings. So if the very first docstring in each API page does import ibis, then we are all good. But due to the reordering I did, this no longer happened here, so I had to add this import. At a higher-level, this isn't great, because it means different docstrings share state, and that depends on their ordering in a page. yuck. But maybe not worth it to fix. Possibly we could del all existing variables with some prelude lines, similar to what is done in docs: add prelude lines to all code samples #7158, but IDK this might all be overkill.

Things that I think should still happen in a followup PR:

I want it to be more obvious how top level stuff is accessed from ibis. e.g. looking at now() in the temporal section, I wish the function signature was ibis.now().
Make things appear in the correct place where possible, eg ibis.random() instead of ibis.expr.api.random().

NickCrews · 2023-09-18T19:43:13Z

I just fixed those broken links, but this is ready for review! It is a little hefty, so I appreciate the effort!

cpcloud

If you can remove the changes to the backend layout this LGTM!

docs/_quarto.yml

NickCrews · 2023-09-20T17:28:22Z

Now top-level backend API is under Backend tab. Looks like this (I'm currently on the Backend/top level page, showing off how the expressions drop-down doesn't contain backend stuff):

NickCrews · 2023-09-20T17:29:43Z

I am getting warning: (but still builds)

Warning: The computation used to determine source line information from the engine timed out.
Line number information will be unavailable and/or inaccurate.

is this to be expected or did I break something?

lostmygithubaccount · 2023-09-20T19:07:33Z

I am getting

Warning: The computation used to determine source line information from the engine timed out.
Line number information will be unavailable and/or inaccurate.

is this to be expected or did I break something?

I've never seen this before working w/ Quarto

I will give a drive-by comment while I'm here that I don't agree w/ hiding the backend docs within the API docs. I understand that it makes sense, as they are API docs to a large extent, but it's useful for users IMO to easily see the list of available backends at a top-level and we can do more platform-specific content in those pages going forward

NickCrews · 2023-09-20T22:15:52Z

Ah I think my latest screenshot was confusing. The backend stuff is NOT underneath the rest of the API stuff, it's in its own top level tab as it was before.

docs/_quarto.yml

cpcloud

This LGTM!

@lostmygithubaccount Can you give a review?

lostmygithubaccount · 2023-09-21T15:58:32Z

where is this coming from? should be "Top-level backend API"

I can only see it in the output html file

lostmygithubaccount

LGTM -- can ignore that nit but if it's easy to fix that'd be nice for consistency

NickCrews · 2023-09-21T16:03:34Z

I will push those two fixes!

NickCrews · 2023-09-21T17:25:44Z

fixed the title (I messed up that screenshot, it was a from a stale build of quartodoc, now it is correct)
moved least, greatest, ifelse to ALSO be in generic. I kept them in the old place too for discoverability.

cpcloud · 2023-09-26T11:53:56Z

docs/_quarto.yml

@@ -111,6 +111,7 @@ website:
      collapse-level: 2
      contents:
        - support_matrix.qmd
+        - reference/connection.qmd


Can you move this to be only in the API docs? I feel like we should keep the backend tab to only contain the support matrix and the backends and nothing else. Otherwise it looks cluttered to me.

Sure. Under what section and what should the page be named?

Can you add it this in a follow up PR? In that PR I think you remove this section and let the API docs show up as they usually do under the Reference tab.

machow · 2023-09-26T16:03:58Z

RE

I want it to be more obvious how top level stuff is accessed from ibis. e.g. looking at now() in the temporal section, I wish the function signature was ibis.now().

Just a heads up, in quartodoc you can set signature_name: full to show the full path to an object in its signature (e.g. ibis.now()). The tricky thing is that you probably don't want the long signatures in methods, so you may need to set it just for those top level functions. (It looks like signature_name is undocumented :/ ).

Here are the docs on setting options: https://machow.github.io/quartodoc/get-started/basic-content.html#setting-default-options

cpcloud · 2023-09-27T19:41:45Z

docs/_quarto.yml

-            - name: random
-              dynamic: true
-            - name: range_window
+            - name: set_backend


Actually can you add these in a follow up PR? It's hard to see the structural changes here without building the docs.

Not quite sure what you mean by "these"? In my latest push I didn't move anything to underneath the Backends tab. Now just the "top-level" section only contains connection stuff and is renamed "Connection API". Hopefully this is clear enough.

I wish quarto had a preview feature for PRs like this, like readthedocs does... :(

Oh, do you mean just remove commit b3429e9 from this PR and follow up with that later?

Sorry! By "these" I mean the set_backend/get_backend/connect methods.

I assumed b3429e9 so, so I removed it from the commit stack.

Ah, now I see your clarification, thanks! I think now your concern is rendered useless, as now these methods aren't getting moved. Everything else is just getting moved out, and this section is getting renamed.

Per ibis-project#7147

This was failing to render in the reference sections of the docs.

NickCrews · 2023-09-27T20:39:34Z

OK, I removed b3429e9 from this PR because it is a bit unrelated and clutters up the main structure here.

In a followup PR I want to

include b3429e9
change to signature_name: full as @machow describes

I think now every comment has been addressed, but please double check me.

docs/_quarto.yml

cpcloud · 2023-09-27T22:19:52Z

I think this is good to go in now!

I moved Connections API to its own section, and fixed a few failing references.

NickCrews · 2023-09-27T22:53:54Z

Money, thank you so much for finishing this up and getting it merged!

Now the signatures appear as `ibis.random()` instead of just `random()`. Per ibis-project#7159 (comment) Before, quartodoc wasn't even respecting this option, because it was incorrectly definied at the wrong nesting level. I had to move the option out of the "member_options" section for any change to occur.

Now the signatures appear as `ibis.random()` instead of just `random()`. Per #7159 (comment) Before, quartodoc wasn't even respecting this option, because it was incorrectly definied at the wrong nesting level. I had to move the option out of the "member_options" section for any change to occur.

NickCrews force-pushed the docs-reference-move branch from f8c1319 to 6f66df5 Compare September 14, 2023 23:23

NickCrews mentioned this pull request Sep 14, 2023

docs: add prelude lines to all code samples #7158

Closed

NickCrews force-pushed the docs-reference-move branch from 6f66df5 to 216a2f1 Compare September 18, 2023 19:42

cpcloud requested changes Sep 20, 2023

View reviewed changes

docs/_quarto.yml Outdated Show resolved Hide resolved

NickCrews force-pushed the docs-reference-move branch from 216a2f1 to 83c9e5d Compare September 20, 2023 17:26

cpcloud added this to the 7.0 milestone Sep 21, 2023

cpcloud reviewed Sep 21, 2023

View reviewed changes

docs/_quarto.yml Outdated Show resolved Hide resolved

cpcloud reviewed Sep 21, 2023

View reviewed changes

docs/_quarto.yml Outdated Show resolved Hide resolved

cpcloud reviewed Sep 21, 2023

View reviewed changes

docs/_quarto.yml Outdated Show resolved Hide resolved

cpcloud added the docs Documentation related issues or PRs label Sep 21, 2023

cpcloud approved these changes Sep 21, 2023

View reviewed changes

lostmygithubaccount approved these changes Sep 21, 2023

View reviewed changes

NickCrews force-pushed the docs-reference-move branch from 83c9e5d to 31db5ab Compare September 21, 2023 17:24

NickCrews force-pushed the docs-reference-move branch from 31db5ab to c0db0f5 Compare September 22, 2023 17:43

cpcloud reviewed Sep 26, 2023

View reviewed changes

cpcloud reviewed Sep 27, 2023

View reviewed changes

NickCrews added 3 commits September 27, 2023 11:59

docs(reference): soft-deprecate ibis.where

3da2342

Per ibis-project#7147

docs(reference): fix ibis.ifelse() docstring

1ac1e13

docs: import ibis in doctests

c9ac8cb

This was failing to render in the reference sections of the docs.

NickCrews force-pushed the docs-reference-move branch from c0db0f5 to 14d5069 Compare September 27, 2023 20:22

docs(reference): move numeric/bool API from global

84d1493

NickCrews added 5 commits September 27, 2023 12:27

docs(reference): move generic API from global

d89b697

docs(reference): move Table API from global

7f42a27

docs(reference): move temporal API from global

9a2061a

docs(reference): move collections API from global

b28ad64

docs(reference): move types API from global

325e3c3

NickCrews force-pushed the docs-reference-move branch from 14d5069 to d174964 Compare September 27, 2023 20:27

docs(reference): rename top-level to connection

554c73a

NickCrews force-pushed the docs-reference-move branch 2 times, most recently from b3429e9 to 554c73a Compare September 27, 2023 20:38

docs: fix numerics and move connection apis elsewhere

0ef7629

NickCrews commented Sep 27, 2023

View reviewed changes

docs/_quarto.yml Outdated Show resolved Hide resolved

chore: remove top-level package

fa84e1c

cpcloud approved these changes Sep 27, 2023

View reviewed changes

cpcloud enabled auto-merge (rebase) September 27, 2023 22:35

cpcloud merged commit 44c5a2b into ibis-project:master Sep 27, 2023

NickCrews mentioned this pull request Sep 29, 2023

docs(reference): improve signatures #7262

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Reorganize reference v2 #7159

Docs: Reorganize reference v2 #7159

NickCrews commented Sep 14, 2023 •

edited

Loading

NickCrews commented Sep 18, 2023

cpcloud left a comment

NickCrews commented Sep 20, 2023 •

edited

Loading

NickCrews commented Sep 20, 2023 •

edited

Loading

lostmygithubaccount commented Sep 20, 2023

NickCrews commented Sep 20, 2023

cpcloud left a comment

lostmygithubaccount commented Sep 21, 2023 •

edited

Loading

lostmygithubaccount left a comment

NickCrews commented Sep 21, 2023

NickCrews commented Sep 21, 2023

cpcloud Sep 26, 2023

NickCrews Sep 26, 2023

cpcloud Sep 27, 2023

machow commented Sep 26, 2023

cpcloud Sep 27, 2023

NickCrews Sep 27, 2023

NickCrews Sep 27, 2023

cpcloud Sep 27, 2023

NickCrews Sep 27, 2023 •

edited

Loading

NickCrews Sep 27, 2023

NickCrews commented Sep 27, 2023 •

edited

Loading

cpcloud commented Sep 27, 2023

NickCrews commented Sep 27, 2023

Docs: Reorganize reference v2 #7159

Docs: Reorganize reference v2 #7159

Conversation

NickCrews commented Sep 14, 2023 • edited Loading

NickCrews commented Sep 18, 2023

cpcloud left a comment

Choose a reason for hiding this comment

NickCrews commented Sep 20, 2023 • edited Loading

NickCrews commented Sep 20, 2023 • edited Loading

lostmygithubaccount commented Sep 20, 2023

NickCrews commented Sep 20, 2023

cpcloud left a comment

Choose a reason for hiding this comment

lostmygithubaccount commented Sep 21, 2023 • edited Loading

lostmygithubaccount left a comment

Choose a reason for hiding this comment

NickCrews commented Sep 21, 2023

NickCrews commented Sep 21, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

machow commented Sep 26, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

NickCrews Sep 27, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

NickCrews commented Sep 27, 2023 • edited Loading

cpcloud commented Sep 27, 2023

NickCrews commented Sep 27, 2023

NickCrews commented Sep 14, 2023 •

edited

Loading

NickCrews commented Sep 20, 2023 •

edited

Loading

NickCrews commented Sep 20, 2023 •

edited

Loading

lostmygithubaccount commented Sep 21, 2023 •

edited

Loading

NickCrews Sep 27, 2023 •

edited

Loading

NickCrews commented Sep 27, 2023 •

edited

Loading