documentation rework (#115)

- bumped mkdocs-material to 9.5.7 - bumped other docs dependencies to latest versions - bumped to new mkdocstrings python provider - rewrote doc-stubs generator based on mkdocstrings example recipe, fixed weird __init__ behavior - light/dark theme support with a toggle - new CSS, very pretty! - fixed broken absolute links - some small text changes here and there
ro-py · Feb 4, 2024 · 413986d · 413986d
1 parent fd217a0
commit 413986d
Show file tree

Hide file tree

Showing 19 changed files with 214 additions and 172 deletions.
diff --git a/.github/workflows/dev-docs.yml b/.github/workflows/dev-docs.yml
@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
     inputs:
       name:
-        description: "MkDocs Deploy"
+        description: "Deploy docs (dev)"
   push:
     branches:
       - "main"
@@ -30,9 +30,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          pip install git+https://github.com/squidfunk/[email protected]
-          pip install mkdocstrings[python-legacy] httpx mkdocs-literate-nav mkdocs-gen-files mike
-
+          pip install mkdocs-material==9.5.7 mkdocs-section-index==0.3.8 mkdocstrings==0.24.0 mkdocstrings-python==1.8.0 mkdocs-literate-nav==0.6.1 mkdocs-gen-files==0.5.0 mkdocs-autorefs==0.5.0 mike==2.0.0
       - name: Configure Git user
         run: |
           git config --local user.email "github-actions[bot]@users.noreply.github.com"

diff --git a/.github/workflows/release-docs.yml b/.github/workflows/release-docs.yml
@@ -6,7 +6,7 @@ on:
   workflow_dispatch:
     inputs:
       name:
-        description: "Deploy Docs (release)"
+        description: "Deploy docs (release)"
 
 jobs:
   mkdocs:
@@ -24,8 +24,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          pip install git+https://github.com/squidfunk/[email protected]
-          pip install mkdocstrings[python-legacy] httpx mkdocs-literate-nav mkdocs-gen-files mike
+          pip install mkdocs-material==9.5.7 mkdocs-section-index==0.3.8 mkdocstrings==0.24.0 mkdocstrings-python==1.8.0 mkdocs-literate-nav==0.6.1 mkdocs-gen-files==0.5.0 mkdocs-autorefs==0.5.0 mike==2.0.0
 
       - name: Configure Git user
         run: |

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -1,3 +1,8 @@
+---
+search:
+  exclude: true
+---
+
 * [Overview](index.md)
 * [Tutorials](tutorials/index.md)
     * [Get Started](tutorials/get-started.md)
@@ -7,6 +12,4 @@
 	* [Pagination](tutorials/pagination.md)
 	* [ROBLOSECURITY](tutorials/roblosecurity.md)
 	* [Bases](tutorials/bases.md)
-	* [Extensions](tutorials/extensions.md)
-	* [Migrating to v2.0](tutorials/migrating.md)
 * [Code Reference](reference/)
diff --git a/docs/assets/theme.css b/docs/assets/theme.css
diff --git a/docs/gen_doc_stubs.py b/docs/gen_doc_stubs.py
diff --git a/docs/index.md b/docs/index.md
@@ -1,16 +1,14 @@
 <p align="center">
-    <img src="./assets/logo-wordmark.svg" alt="ro.py" width="50%" />
-
+    <img src="./assets/logo-wordmark.svg" alt="ro.py" width="50%" /> 
     <br /> <br />
-
     ro.py is an asynchronous, object-oriented wrapper for the Roblox web API.
 </p> 
 
 ## Features
-- **Asynchronous**: ro.py works well with asynchronous frameworks like [FastAPI](https://fastapi.tiangolo.com/) and 
-[discord.py](https://github.com/Rapptz/discord.py).  
 - **Easy**: ro.py's client-based model is intuitive and easy to learn. 
   It abstracts away API requests and leaves you with simple objects that represent data on the Roblox platform.
+- **Asynchronous**: ro.py works well with asynchronous frameworks like [FastAPI](https://fastapi.tiangolo.com/) and 
+[discord.py](https://github.com/Rapptz/discord.py).  
 - **Flexible**: ro.py's Requests object allows you to extend ro.py beyond what we've already implemented.
 
 ## Installation

diff --git a/docs/overrides/assets/stylesheets/main.css b/docs/overrides/assets/stylesheets/main.css
diff --git a/docs/overrides/main.html b/docs/overrides/main.html
@@ -1,12 +1,5 @@
 {% extends "base.html" %}
 
-{% block extrahead %}
-  <link
-    rel="stylesheet"
-    href="{{ 'overrides/assets/stylesheets/main.css' | url }}"
-  />
-{% endblock %}
-
 {% block announce %}
   <a href="https://discord.gg/N8yUdkSJwA">
     For updates and support, join the

diff --git a/docs/scripts/gen_ref_pages.py b/docs/scripts/gen_ref_pages.py
@@ -0,0 +1,36 @@
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+src = Path(__file__).parent.parent.parent / "roblox"
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+
+    if not parts:
+        print(f"skipping {module_path.parts}")
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: roblox.{ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())
diff --git a/docs/stylesheets/main.css b/docs/stylesheets/main.css
@@ -0,0 +1,107 @@
+:root {
+    /* font-size: 125% !important; */
+}
+
+[data-md-color-scheme=slate] {
+    --md-code-bg-color: hsl(0 0% 100% / 1.5%);
+    --md-default-bg-color: hsl(0 0% 6%);
+
+    --md-footer-bg-color: hsl(0 0% 12% / 75%);
+    --md-footer-bg-color--dark: transparent;
+
+}
+
+[data-md-color-scheme=slate] .md-header,
+[data-md-color-scheme=slate] .md-tabs {
+    background: hsl(0 0% 10% / 75%);
+}
+
+[data-md-color-scheme=slate] .md-typeset table {
+    --md-default-bg-color: hsl(0 0% 7.5%);
+    --md-typeset-table-color: hsl(0 0% 95% / 3%);
+}
+
+[data-md-color-scheme=slate] .md-typeset details {
+    background: hsl(0 0% 100% / 2%);
+}
+
+[data-md-color-scheme=default] {
+    --md-footer-bg-color: hsl(0 0% 97%);
+    --md-footer-bg-color--dark: transparent;
+    --md-footer-fg-color: hsl(0 0% 0%);
+    --md-footer-fg-color--lighter: hsl(0 0% 33%);
+    --md-footer-fg-color--light: hsl(0 0% 0%);
+    --md-code-bg-color: hsl(0 0% 0% / 2.33%);
+}
+
+[data-md-color-scheme=default] .md-header,
+[data-md-color-scheme=default] .md-tabs {
+    background: hsl(0 0% 100% / 75%);
+}
+
+[data-md-color-scheme=default] .md-search__form {
+    background: hsl(0 0% 0% / 5%);
+}
+
+[data-md-color-scheme=default] .md-search__form:hover {
+    background: hsl(0 0% 0% / 10%);
+}
+
+[data-md-color-scheme=default] .md-typeset details {
+    background: hsl(0 0% 0% / 0.5%);
+}
+
+.md-header, .md-tabs {
+    backdrop-filter: blur(32px);
+    -webkit-backdrop-filter: blur(32px);
+}
+
+.md-typeset table {
+    border-radius: .3rem !important;
+}
+
+.md-banner strong {
+    white-space: nowrap;
+}
+
+.md-banner a {
+    color: inherit;
+    font-size: 0.8rem;
+}
+
+.md-typeset .admonition, .md-typeset details {
+    border-width: 1px;
+    border-radius: .3rem !important;
+    overflow: clip;
+}
+
+.md-typeset details {
+    border: none;
+}
+
+.admonition-title {
+    border-radius: 0rem !important;
+}
+
+.md-header--shadow {
+    box-shadow: 0 0 .2rem #0000001a, 0 .2rem .4rem #0001;
+}
+
+.md-search__form {
+    border-radius: .15rem !important;
+}
+[data-md-toggle=search]:checked~.md-header .md-search__form {
+    border-bottom-left-radius: 0 !important;
+    border-bottom-right-radius 0 !important;
+}
+
+.doc-contents .quote .highlight {
+    margin: 0;
+    margin-left: -.6rem;
+    margin-right: -.6rem;
+    --md-code-bg-color: transparent;
+}
+
+.doc-contents .quote .highlighttable {
+    margin: 0;
+}
diff --git a/docs/tutorials/authentication.md b/docs/tutorials/authentication.md
@@ -1,6 +1,6 @@
 # Authentication
 To authenticate our client, we need our .ROBLOSECURITY token. To learn about why we need this and how to get it, 
-please see [ROBLOSECURITY](/roblosecurity). 
+please see [ROBLOSECURITY](./roblosecurity.md). 
 
 Once we have our token, we can add it to our client by passing it as the first parameter. 
 Use the following code and replace `TOKEN` with the .ROBLOSECURITY token grabbed earlier to authenticate your client.

diff --git a/docs/tutorials/error-handling.md b/docs/tutorials/error-handling.md
@@ -82,8 +82,7 @@ except Unauthorized as exception:
     print("URL:", exception.response.url)
 ```
 Roblox also returns extra error data, which is what you see in our error messages. 
-We can access this with the `.errors` attribute, which is a list of 
-[`ResponseError`](/reference/roblox/utilities/exceptions/#roblox.utilities.exceptions.ResponseError):
+We can access this with the `.errors` attribute, which is a list of [`ResponseError`][roblox.utilities.exceptions.ResponseError]:
 ```python
 group = await client.get_group(1)
 try:

diff --git a/docs/tutorials/migrating.md b/docs/tutorials/migrating.md
diff --git a/docs/tutorials/pagination.md b/docs/tutorials/pagination.md
@@ -3,9 +3,9 @@ Certain Roblox endpoints are paginated. This means that going through their data
 pages of a book - you start at page 1 and then you can move forwards or backwards until you reach the start or the end.
 
 This can be annoying when all you want is "every member in a group" or "the last 10 posts on a group wall", so ro.py
-abstracts this away into a "PageIterator" that you can use to loop over your data.
+abstracts this away into an iterator that you can use to loop over your data.
 
-As an example, the `Client.user_search()` function takes in a keyword (like "builderman") and returns a `PageIterator`
+As an example, the [`Client.user_search()`][roblox.client.Client.user_search] function takes in a keyword (like "builderman") and returns a [`PageIterator`][roblox.utilities.iterators.PageIterator]
 which you can loop through to get the search results.
 
 ## Looping through items
@@ -45,7 +45,7 @@ async for page in client.user_search("builderman", page_size=100).pages():
 ```
 
 ## Flattening into a list
-If we want to turn all of this data into one list, we can use `flatten()`. Be careful, as this isn't ideal for large
+If we want to turn all of this data into one list, we can use [`flatten()`][roblox.utilities.iterators.PageIterator.flatten]. Be careful, as this isn't ideal for large
 sets of data and may use more memory. Because we turn this iterator into a list, we can use a normal for loop now:
 ```python
 for user in await client.user_search("boatbomber").flatten():

diff --git a/docs/tutorials/roblosecurity.md b/docs/tutorials/roblosecurity.md
@@ -35,18 +35,18 @@ To grab your .ROBLOSECURITY cookie, log into your account on the Roblox website
     browser, clicking the arrow next to `roblox.com`, opening up the "Cookies" folder, clicking ".ROBLOSECURITY",
     clicking on the "Content" text once, pressing ++control+a++, and then pressing ++control+c++
     (make sure **not** to double-click this field as you won't select the entire value!)  
-    
-    ![](/assets/screenshots/ChromeCookie.png){: style="width: 400px"}
+
+    ![](../assets/screenshots/ChromeCookie.png){: style="width: 400px"}
 
     Alternatively, you can access the cookie by going to https://www.roblox.com/, pressing ++control+shift+i++ to access
     the Developer Tools, navigating to the "Application" tab, opening up the arrow next to "Cookies" on the sidebar on
     the left, clicking the `https://www.roblox.com` item underneath the Cookies button, and then copying the
     .ROBLOSECURITY token by double-clicking on the value and then hitting ++control+c++.
 
-    ![](/assets/screenshots/ChromeDevTools.png){: style="height: 436px"}
+    ![](../assets/screenshots/ChromeDevTools.png){: style="height: 436px"}
 === "Firefox"
     You can access the cookie by going to https://www.roblox.com/ and pressing ++shift+f9++,
     pressing the "Storage" tab button on the top, opening up the "Cookies" section in the sidebar on the left, 
     clicking the `https://www.roblox.com` item underneath it,
     and then copying the .ROBLOSECURITY token by double-clicking on the value and then hitting ++control+c++.
-    ![](/assets/screenshots/FirefoxCookie.jpeg)
+    ![](../assets/screenshots/FirefoxCookie.jpeg)