Merge pull request #16 from LBRYFoundation/api-docs

Api docs

astro.config.mjs

@@ -1,6 +1,7 @@
 import { defineConfig } from 'astro/config';
 import codeblocks from "@thewebforge/astro-code-blocks";
 import preload from "astro-preload";
+import * as config from './src/config.js';
 
 import mdx from "@astrojs/mdx";
 
@@ -11,5 +12,6 @@ export default defineConfig({
     // Copy Button Options
     copyButtonTitle: 'Copy',
     copyButtonTooltip: 'Copied to clipboard',
-}), mdx()]
+  }), mdx()],
+  redirects: config.REDIRECTS,
 });

src/components/APIArguments.astro

@@ -0,0 +1,56 @@
+---
+const {args} = Astro.props;
+---
+
+{(args && args.length) ? (
+    <h3>Arguments</h3>
+    <table class="arguments">
+        <tbody>
+            {args.map(arg=>(
+                <tr class="argument">
+                    <th>
+                        <strong>{arg.name}</strong>
+                        <br/>
+                        <span>
+                            {!arg.is_required && (
+                                "optional "
+                            )}
+                            {arg.type}
+                        </span>
+                    </th>
+                    <th>
+                        <span>{arg.description}</span>
+                    </th>
+                </tr>
+        ))}
+        </tbody>
+    </table>
+) : ''}
+<style>
+    .arguments {
+        border: 1px solid var(--tertiary-background);
+    }
+
+    .arguments .argument {
+        background-color: var(--tertiary-background);
+        border-bottom: 1px solid var(--tertiary-background);
+    }
+
+    .arguments .argument th {
+        text-align: left;
+        padding: 0.25rem 1rem;
+    }
+
+    .arguments .argument span {
+        text-align: left;
+        font-weight: normal;
+    }
+
+    .arguments .argument .left, .arguments .argument .right {
+        padding: 0.5rem 1rem;
+    }
+
+    .arguments .argument:nth-child(2n) {
+        background-color: var(--secondary-background);
+    }
+</style>

src/components/APIExamples.astro

@@ -0,0 +1,101 @@
+---
+import { Code } from "astro/components";
+import Collapsible from "./Collapsible.astro";
+
+const {examples, cmd} = Astro.props;
+
+if (!examples) return;
+
+// Treat title and output as metadata and remove from examples
+const title = examples.title;
+const output = examples.output;
+delete examples.title;
+delete examples.output;
+
+const options = (Object.keys(examples).map(example=> `.${example}`)).join(', ');
+
+function setExample(example, cmd){
+                console.log(example, cmd);
+                document.body.classList.toggle(example);
+            }
+
+---
+    {examples ? (
+        <div class="examples">
+            <h3>Examples</h3>
+            <h4>{title}</h4>
+            <div class="buttons">
+                {Object.keys(examples).map(example=>(
+                    <button data-example={example}>{example}</button>
+                ))}
+            </div>
+            <div class="commands">
+                {Object.keys(examples).map(example=>(
+                    <div class:list={["example", cmd, example]}>
+                        {/* <p>{example}</p> */}
+                        <Code lang={"bash"} code={`${examples[example]}`} />
+                    </div>
+                ))}
+            </div>
+            {output && (
+                <Collapsible>
+                    <span slot="head">Output:</span>
+                    <Code slot="body" lang={"json"} code={`${output}`} />
+                </Collapsible>
+            )}
+        </div>
+        <script define:vars={{examples, cmd}}>
+            
+            document.querySelectorAll(`.${cmd} button`).forEach(btn=>{
+                btn.addEventListener('click', (e)=>{
+                    Object.keys(examples).map(example=>{
+                        document.body.classList.remove(example);
+                    });
+                    document.body.classList.add(btn.getAttribute('data-example'));
+                })
+            })
+            
+        </script>
+    ) : ''}
+</div>
+<style>
+
+    .examples {
+        display: flex;
+        flex-direction: column;
+        gap: 1rem;
+        padding: 1rem;
+        border-radius: 8px;
+        border: 3px solid var(--secondary-background);
+    }
+
+    .commands {
+        display: flex;
+        flex-direction: column;
+        gap: 25px;
+    }
+
+    .example {
+        display: none;
+    }
+
+    .buttons {
+        display: flex;
+        gap: 0.75rem;
+    }
+
+    button {
+        color: var(--primary);
+        padding: 0.5em 0.75rem;
+        border-radius: 8px;
+        border: none;
+        background-color: var(--secondary-background);
+    }
+
+    body:not(.curl, .lbrynet, .python, .cli) button:first-of-type, body.curl button[data-example=curl], body.lbrynet button[data-example=lbrynet], body.python button[data-example=python], body.cli button[data-example=cli] {
+        font-weight: bold;
+        color: var(--accent);
+        outline: 1px solid var(--accent);
+        /* background-color: var(--accent); */
+    }
+</style>

src/components/Collapsible.astro

@@ -0,0 +1,49 @@
+---
+const {open} = Astro.props;
+---
+
+<details class="collapsible" {open}>
+    <summary>
+        <p><slot name="head"></p>
+        <p class="arrow">&#8595;</p>
+    </summary>
+    <div>
+        <slot name="body"/>
+    </div>
+</details>
+<style>
+    .collapsible summary::-webkit-details-marker {
+        display: none;
+    }
+
+    .collapsible {
+        /* width: 90%; */
+        /* padding: 1rem; */
+        border-radius: 1rem;
+        overflow: hidden;
+        outline: 2px solid var(--tertiary-background);
+        background-color: var(--secondary-background);
+    }
+
+    .collapsible summary {
+        display: flex;
+        cursor: pointer;
+        font-weight: bold;
+        justify-content: space-between;
+        padding: 1rem;
+        user-select: none;
+        background-color: var(--tertiary-background);
+    }
+    
+    .collapsible summary p.arrow {
+        transition: transform 0.3s;
+    }
+
+    .collapsible:not([open]) summary {
+        margin-bottom: 1rem;
+    }
+
+    .collapsible[open] summary p.arrow {
+        transform: rotate(180deg);
+    }
+</style>

src/components/Header.astro

@@ -8,6 +8,7 @@ const links = [
   { name: "Overview", href: "/overview" },
   { name: "Playground", href: "/playground" },
   { name: "Resources", href: "/resources"},
+  { name: "API", href: "/api"},
   { name: "Tutorials", href: "/tutorials"},
   { name: "Community", href: "/community"}
 ]

src/config.js

@@ -1,6 +1,7 @@
 export const AWESOME_LBRY = "https://github.com/LBRYFoundation/Awesome-LBRY";
 export const EDIT_PAGE = "Edit this page";
 export const REPOSITORY = "LBRYFoundation/lbry-tech";
+export const GITHUB_ORG = "LBRYFoundation";
 
 export const features = [
     {
@@ -69,3 +70,34 @@ export const featured = [
     description: "Audio media crawler for lbry."
   }
 ]
+
+export const REDIRECTS = {
+  // "/api/blockchain": "/api/lbrycrd",
+  // "/api/lbry": "/api/sdk",
+  // "/api/protocol": "/api/sdk",
+  // "/play": "/playground",
+  // "/repository-standards": "/resources/repository-standards",
+  // "/resources/lbry-claimtrie": "/spec#claimtrie",
+  // "/resources/schema": "/spec#metadata",
+  // "/resources/signing-claim": "/resources/claim-signing",
+  // "/resources/uri": "/spec#urls",
+  // "/resources/video-lbryandroid": "https://odysee.com/video-2018-10-15053403:e",
+  // "/resources/video-lbrycrd": "https://odysee.com/intro-to-LBRYcrd:5",
+  // "/resources/video-lbrydesktop": "https://odysee.com/LBRYAppDesign:7",
+  // "/resources/video-lbrysdk": "https://odysee.com/@lbrytech:1/lbrynet-dev-setup:9",
+  // "/specification": "/spec",
+  // "/tour": "/playground",
+  // "/whitepaper": "/spec"
+}
+
+export const API_REPOS = {
+  "lbry-sdk": {
+    "api": "docs/api.json",
+    "description":  "The LBRY SDK for building decentralized, censorship resistant, monetized, digital content apps.",
+    "playground": true
+  },
+  "lbrycrd": {
+    "api": "contrib/devtools/generated/api_v1.json",
+    "description": "The blockchain that provides the digital content namespace for the LBRY protocol"
+  }
+}

src/pages/api.astro

@@ -0,0 +1,95 @@
+---
+import Layout from '../layouts/Layout.astro';
+
+import * as config from "../config.js";
+
+---
+
+
+<Layout title="API">
+    <div class="wrapper">
+        <h1>Exlore the APIs</h1>
+        <ul class="apis">
+            {Object.keys(config.API_REPOS).map(repo=>(
+                <li class="api">
+                    <h2>{repo}</h2>
+                    <hr/>
+                    <p>{config.API_REPOS[repo].description}</p>
+                    <div class="button-primary"><a href={`/api/${repo}`}>{repo.toUpperCase()} APIs</a></div>
+                    {config.API_REPOS[repo].playground && (
+                        <p class="playground">Available in <a href="/playground">Playground</a></p>
+                    )}
+                </li>
+            ))}
+        </ul>
+    </div>
+    <style>
+        .wrapper {
+            margin: 1rem;
+        }
+
+        h1 {
+            text-align: center;
+            padding-bottom: 1rem;
+        }
+
+        hr {
+            color: var(--accent);
+        }
+
+        .apis {
+            display: flex;
+            justify-content: center;
+            /* align-items: center; */
+            gap: 25px;
+            padding: 0;
+        }
+
+        .apis .api {
+            display: flex;
+            flex-direction: column;
+            max-width: 30%;
+            height: max-content;
+            gap: 1rem;
+            padding: 1rem;
+            border-radius: 1rem;
+        }
+
+        .apis .api h2 {
+            text-align: center;
+            text-transform: uppercase;
+            /* border-bottom: 1px solid var(--accent); */
+        }
+        
+        .apis .api p {
+            text-align: center;
+        }
+
+        .apis .api .button-primary {
+            margin: auto;
+        }
+
+        .apis .api .playground a {
+            color: var(--accent);
+        }
+
+        @media only screen and (max-width: 1000px) {
+            .apis .api {
+                max-width: 50%;
+            }
+        }
+
+        @media only screen and (max-width: 750px) {
+            .apis {
+                flex-direction: column;
+                padding: 0;
+                width: 80%;
+                margin: auto;
+            }
+
+            .apis .api {
+                max-width: unset;
+            }
+        }
+    </style>
+</Layout>

src/pages/api/[repo].astro

@@ -0,0 +1,213 @@
+---
+import Layout from '../../layouts/Layout.astro';
+import TableOfContents from '../../components/TableOfContents.astro';
+import APIArguments from '../../components/APIArguments.astro';
+import APIExamples from '../../components/APIExamples.astro';
+import Collapsible from '../../components/Collapsible.astro';
+
+import * as config from "../../config.js";
+import { Code } from 'astro:components';
+
+export function getStaticPaths() {
+    
+    const paths = Object.keys(config.API_REPOS).map(repo=>{
+        return {params: {repo}};
+    });
+
+    return paths; 
+}
+
+const { repo } = Astro.params;
+
+const tags = (await (await fetch(`https://data.jsdelivr.com/v1/packages/gh/${config.GITHUB_ORG}/${repo}`)).json()).versions;
+tags.unshift({version: "master"});
+
+const tag = tags[0];
+
+let docs = (await (await fetch(`https://cdn.jsdelivr.net/gh/${config.GITHUB_ORG}/${repo}@${tag.version}/${config.API_REPOS[repo].api}`)).json());
+
+
+// Convert lbrycrd docs to the same structure as lbry-sdk
+if (repo === 'lbrycrd') {
+    const crd = {};
+    for (let i in docs) {
+        if (!crd[docs[i].namespace]) crd[docs[i].namespace] = {
+            doc: docs[i].namespace,
+            commands: []
+        };
+        crd[docs[i].namespace].commands.push(docs[i]);
+        console.log(docs[i]);
+        
+        //docs.main[i].command = docs.main[i].name;
+    }
+    docs = crd;
+}
+
+const headings: Array<object> = [];
+
+// Generate headings
+Object.keys(docs).forEach(group=>{
+    headings.push({
+        slug: group,
+        text: group.charAt(0).toUpperCase() + group.substr(1).toLowerCase(),
+        depth: 2
+    });
+
+    docs[group].commands.forEach(cmd=>{
+        headings.push({
+            slug: cmd.name,
+            text: cmd.name,
+            depth: 3
+        });
+    })
+    
+});
+
+---
+
+
+<Layout title={repo}>
+    <div class="wrapper">
+        <section class="sidebar">
+            {(headings && headings.length) ? (
+                <aside id="toc">
+                    <TableOfContents headings={headings} />
+                </aside>
+            ) : ''}
+        </section>
+        
+        <!-- <TableOfContents headings={headings} /> -->
+        <select>
+            {tags.map(tag=>(
+                <option>{tag.version}</option>
+            ))}
+        </select>
+        <div class="main">
+            <div class="description">
+                <h1>{repo} {tag.version}</h1>
+                <p>Methods and signatures provided by <a href={`https://github.com/${config.GITHUB_ORG}/${repo}`}>{repo}</a> are documented below. To build, download, or run the daemon, see the project
+                    <a href={`https://github.com/${config.GITHUB_ORG}/${repo}/blob/${tag.version}/README.md`}>README</a>.
+                </p>
+            </div>
+            <hr/>
+            <div class="commands">
+                {Object.keys(docs).map(header=>(
+                    <section>
+                        <p class="header" id={header}>{header}</p>
+                        {docs[header].commands.map(cmd=>(
+                            <div class:list={["command", cmd.name]}>
+                                <h2 id={cmd.name}>{cmd.name}</h2>
+                                <p>{cmd.description}</p>
+                                <APIArguments args={cmd.arguments}/>
+                                <APIExamples cmd={cmd.name} examples={cmd.examples[0]}/>
+                                <Collapsible open>
+                                    <span slot="head">Returns:</span>
+                                    <Code slot="body" lang={"json"} code={`${cmd.returns || "Not available."}`} class:list={["returns"]} />
+                                </Collapsible>
+                                </div>
+                            <hr/>
+                        ))}
+                    </section>
+                ))}
+            </div>
+        </div>
+    </div>
+    <style>
+        /* Should we have version selector? */
+        select {
+            display: none;
+        }
+
+        .wrapper {
+            padding: 0 1rem;
+        }
+
+        .wrapper .main {
+            padding-inline-end: var(--sidebar-width);
+            transition: 0.3s;
+            overflow-x: hidden;
+            max-width: 1750px;
+            width: calc(100%);
+        }
+
+        .description {
+            padding: 2rem;
+        }
+
+        .description a {
+            color: var(--accent);
+        }
+
+        .commands {
+            display: flex;
+            flex-direction: column;
+            gap: 25px;
+            padding: 1rem;
+        }
+
+        .commands .header {
+            font-size: 1.75rem;
+            font-weight: bold;
+        }
+
+        .commands section {
+            display: flex;
+            flex-direction: column;
+            gap: 25px;
+        }
+        
+        .commands section .command {
+            display: flex;
+            flex-direction: column;
+            gap: 1em;
+            padding: 0 1rem;
+        }
+
+        .wrapper #toc {
+            position: fixed;
+            width: calc(var(--sidebar-width) - 2rem);
+            height: fit-content;
+            max-height: calc(100vh - var(--nav-height)*2 - 2rem * 2);
+            inset-block: 0;
+            inset-inline-end: 2rem;
+            margin: calc(2rem + var(--nav-height)) 0;
+            // background-color: var(--secondary-background);
+            transition: 0.3s;
+            z-index: 10;
+            overflow-y: auto;
+            border-radius: 1em;
+            background-color: var(--secondary-background);
+        }
+
+        @media only screen and (max-width: 1000px) {
+            .wrapper #toc {
+                position: relative;
+                width: var(--sidebar-width);
+                max-height: unset;
+                inset-block: unset;
+                inset-inline-end: unset;
+                margin-top: 0;
+                z-index: 1;
+                background-color: transparent;
+            }
+
+            .wrapper .main {
+                padding-inline-end: unset;
+            }
+        }
+        
+    </style>
+
+    <style is:inline>
+        .commands > section pre {
+            padding: 1em;
+            border-radius: 9px;
+            max-width: 80%;
+            background-color: var(--secondary-background) !important;
+        }
+
+        .commands > section pre code span {
+            white-space: break-spaces;
+        }
+    </style>
+</Layout>

src/styles/global.scss

@@ -108,3 +108,12 @@ a {
 .button-primary:hover {
     transform: scale(1.1);
 }
+
+// API Docs Examples
+body:not(.curl, .lbrynet, .python, .cli) .commands .example:first-of-type {
+    display: block;
+}
+
+body.curl .example.curl, body.lbrynet .example.lbrynet, body.python .example.python, body.cli .example.cli {
+    display: block;
+}