Merge branch 'docs' into 'master'

master
justcool393 2022-11-26 14:40:32 -06:00
commit e1f785c370
6 changed files with 378 additions and 1 deletions

241
docs/api.xml 100644
View File

@ -0,0 +1,241 @@
<?xml version="1.0" encoding="utf-8" ?>
<wadl:application xmlns="http://docbook.org/ns/docbook"
xmlns:wadl="http://wadl.dev.java.net/2009/02"
xmlns:rax="http://docs.rackspace.com/api"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<!--
Want to read this? Lololol fuck you :3
Written in a deprecated format due to it's verbosity and
easy porting to OpenAPI's Swagger, which supports nice
frontends.
View it at /dev/api
-->
<resources xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsdxt="http://docs.rackspacecloud.com/xsd-ext/v1.0"
xmlns:dbaas="http://docs.openstack.org/database/api/v1.0"
xmlns="http://wadl.dev.java.net/2009/02"
base="http://docs.openstack.org/database/api/v1.0"
xml:id="rdrama">
<!-- ################################################## -->
<resource path="/submit"> <!-- INCOMPLETE -->
<method name="POST">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xml:lang="EN"
title="Create post">
<para role="shortdesc">
Submits a post.
</para>
</wadl:doc>
<request>
<param required="true"
name="title"
style="plain"
type="xsd:string">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xml:lang="EN">
<para>The posts title. :emojis: will be parsed as well. Plaintext. No markdown.</para>
</wadl:doc>
</param>
<param required="false"
name="url"
style="plain"
type="xsd:string">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<para>Post URL. Be wary of duplicates.</para>
</wadl:doc>
</param>
<param required="true"
name="body"
style="markdown"
type="xsd:string">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<para>The post in markdown.</para>
</wadl:doc>
</param>
<!-- TODO a fuck ton more -->
</request>
<response status="200">
<param required="false"
name="body"
style="html"
type="xsd:string">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<para>The post you were looking for.</para>
</wadl:doc>
</param>
<!-- Example -->
<representation mediaType="application/json">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<xsdxt:code xmlns:db="http://docbook.org/ns/docbook">
<programlisting language="javascript">{
"our": "example, here",
"our": "example, here"
}</programlisting>
</xsdxt:code>
</wadl:doc>
</representation>
</response>
<response status="400">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<para>Not found</para>
</wadl:doc>
</response>
</method>
</resource>
<!-- ################################################## -->
<resource path="/@{username}/message"> <!-- INCOMPLETE -->
<method name="POST">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xml:lang="EN"
title="Create post">
<para role="shortdesc">
Sends a user a message
</para>
</wadl:doc>
<request>
<param required="true"
name="username"
style="url"
type="xsd:string">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<para>User URL</para>
</wadl:doc>
</param>
<param required="true"
name="data"
style="markdown"
type="xsd:string">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<para>Message data to the user.</para>
</wadl:doc>
</param>
<!-- TODO a fuck ton more -->
</request>
<response status="200">
<!-- <param required="false" -->
<!-- name="body" -->
<!-- style="html" -->
<!-- type="xsd:string"> -->
<!-- <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"> -->
<!-- <para></para> -->
<!-- </wadl:doc> -->
<!-- </param> -->
<!-- Example -->
<representation mediaType="application/json">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<xsdxt:code xmlns:db="http://docbook.org/ns/docbook">
<programlisting language="javascript">{
}</programlisting>
</xsdxt:code>
</wadl:doc>
</representation>
</response>
<response status="400">
<representation mediaType="application/xml" element="csapi:badRequest"/>
<representation mediaType="application/json"/>
</response>
</method>
</resource>
<!-- ################################################## -->
<resource path="/comment"> <!-- INCOMPLETE -->
<method name="POST">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xml:lang="EN"
title="Create post">
<para role="shortdesc">
Creates a comment on a post, or replies to a comment
</para>
</wadl:doc>
<request>
<param required="true"
name="parent_fullname"
style="plain"
type="xsd:url">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<para>ID of the parent post. Starts with <code>p_</code> for a parent submission, and <code>c_</code> for a comment submission. Anything else will emit a 400.</para>
</wadl:doc>
</param>
<param required="true"
name="submission"
style="plain"
type="xsd:string">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<para>Parent submission (the id, right?)</para>
</wadl:doc>
</param>
<param required="true"
name="body"
style="markdown"
type="xsd:string">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<para>Your messages content</para>
</wadl:doc>
</param>
<param required="true"
name="submission"
style="plain"
type="xsd:string">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<para>Parent submission (the id, right?)</para>
</wadl:doc>
</param>
<param required="true"
name="over_18"
style="plain"
type="xsd:boolean">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<para>If this post is marked as sensitive.</para>
</wadl:doc>
</param>
<!-- TODO a fuck ton more -->
</request>
<!-- SUCCESS -->
<response status="200">
<param required="false"
name="body"
style="html"
type="xsd:string">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<para></para>
</wadl:doc>
</param>
<!-- Example -->
<representation mediaType="application/json">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<xsdxt:code xmlns:db="http://docbook.org/ns/docbook">
<programlisting language="javascript">{
}</programlisting>
</xsdxt:code>
</wadl:doc>
</representation>
</response>
<!-- ERRORS -->
<response status="400">
<representation mediaType="application/xml" element="csapi:badRequest"/>
<representation mediaType="application/json"/>
</response>
<response status="403">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<para>User is exiled from the hole, or needs extra permissions.</para>
<para>User is banned and needs to do better.</para>
</wadl:doc>
<representation mediaType="application/xml" element="csapi:badRequest"/>
<representation mediaType="application/json"/>
</response>
</method>
</resource>
<!-- ################################################## -->
</resources>
</wadl:application>

View File

@ -6406,3 +6406,43 @@ div.markdown {
.modlog-action:not(:first-of-type) {
border-top: 1px solid var(--gray-400) !important;
}
/* Documentation elements */
#docs-page .docs-path {
font-size: 1.7rem;
}
#docs-page .docs-request {
background-color: var(--primary);
padding: 3px 8px;
border-radius: 4px;
}
#docs-page .docs-response {
background-color: var(--secondary);
padding: 3px 8px;
border-radius: 4px;
}
#docs-page .doc-snippet {
padding: 4px;
}
#docs-page .doc-snippet table {
border: 1px solid var(--secondary);
}
#docs-page .doc-snippet table p {
margin: 0;
}
#docs-page .doc-snippet table tr th {
color: #aaa;
border-bottom: 1px solid var(--secondary);
}
#docs-page .doc-snippet table tr td,
#docs-page .doc-snippet table tr th {
padding: 4px 8px;
border-right: 1px solid var(--secondary);
}

View File

@ -20,6 +20,7 @@ from files.routes.jinja2 import *
from .admin import *
from .comments import *
from .errors import *
from .docs import *
from .reporting import *
from .front import *
from .login import *

View File

@ -79,6 +79,7 @@ def post_pid_comment_cid(cid, pid=None, anything=None, v=None, sub=None):
else: template = "submission.html"
return render_template(template, v=v, p=post, sort=sort, comment_info=comment_info, render_replies=True, sub=post.subr)
#- API
@app.post("/comment")
@limiter.limit("1/second;20/minute;200/hour;1000/day")
@auth_required
@ -91,7 +92,7 @@ def comment(v):
id = parent_fullname[2:]
parent_comment_id = None
rts = False
if parent_fullname.startswith("p_"):
parent = get_post(id, v=v)
parent_post = parent

View File

@ -0,0 +1,13 @@
import xml
import xml.etree.ElementTree as ET
from files.__main__ import app, cache, limiter
tree = ET.parse('docs/api.xml')
@app.get("/dev/api")
@auth_desired
def get_docs_page():
# TODO cache
root = tree.getroot()
return render_template("docs.html", root=tree.getroot())

View File

@ -0,0 +1,81 @@
{% extends "default.html" %}
{#% Some macros %#}
{% macro docbook_read(info) -%}
{% for p in info -%}
{#% Lazy hack, not """conforming""" to docbook %#}
<p>
{{- p.text -}}
</p>
{%- endfor %}
{%- endmacro %}
{%- macro param_table(info) -%}
<table>
<tr>
<th>Param</th>
<th>Description</th>
<th>Type</th>
<th>Format</th>
<th>Required</th>
</tr>
{% for param in info %}
<tr>
<td><b>{{ param.attrib.name }}</b></td>
<td>{{- docbook_read(param[0]) -}}</td>
<td><i>{{ param.attrib.type }}</i></td>
<td>{{ param.attrib.style }}</td>
<td>{{ param.attrib.required }}</td>
</tr>
{% endfor %}
</table>
{%- endmacro -%}
{% block pagetitle %}Documentation{% endblock %}
{% block content %}
<div id="docs-page">
<h1>rDrama REST Api Documentaion</h1>
<p><em class="text-warning">Warning: This documentation is SHIT, so get
used to it</em></p>
<p>You're probably here because you want to create your own application
which calls our REST api. Some of the stuff you see here might seem
ugly (it is), but it's mainly inherited from the old Ruqqus API.</p>
<p><em class="text-info">This documentation is generated from an XML WADL file.</em></p>
<hr>
{% for res in root[0] %}
<div class="doc-snippet">
{#% There's usually only one method, but this is more correct %#}
{% for method in res %}
<h1 class="docs-path">
<span class="docs-request">
{{- method.attrib.name -}}
</span>
{{ res.attrib.path }}
</h1>
{% for info in method %}
{% if info.tag == "{http://wadl.dev.java.net/2009/02}doc" %}
{{ docbook_read(info) }}
{% elif info.tag == "{http://wadl.dev.java.net/2009/02}request" %}
{{ param_table(info) }}
{% elif info.tag == "{http://wadl.dev.java.net/2009/02}response" %}
<h4>Response <span class="docs-response">{{ info.attrib.status }}</span></h4>
{% for response_child in info %}
{% if response_child.tag == "{http://wadl.dev.java.net/2009/02}param" %}
{{ param_table(info) }}
{% elif response_child.tag == "{http://wadl.dev.java.net/2009/02}doc" %}
{{ docbook_read(response_child) }}
{% endif %}
{% endfor %}
{% endif %}
{% endfor %}
{% endfor %}
</div>
{% endfor %}
</div>
{% endblock %}