mirror of
https://github.com/urbit/developers.urbit.org.git
synced 2024-08-16 17:20:35 +03:00
add docs app docs
This commit is contained in:
parent
189797a48b
commit
ea7c0ac269
2
content/reference/additional/dist/_index.md
vendored
2
content/reference/additional/dist/_index.md
vendored
@ -1,6 +1,6 @@
|
|||||||
+++
|
+++
|
||||||
title = "Software Distribution"
|
title = "Software Distribution"
|
||||||
weight = 900
|
weight = 90
|
||||||
sort_by = "weight"
|
sort_by = "weight"
|
||||||
insert_anchor_links = "right"
|
insert_anchor_links = "right"
|
||||||
+++
|
+++
|
||||||
|
20
content/reference/additional/docs-app/_index.md
Normal file
20
content/reference/additional/docs-app/_index.md
Normal file
@ -0,0 +1,20 @@
|
|||||||
|
+++
|
||||||
|
title = "Docs App"
|
||||||
|
weight = 100
|
||||||
|
+++
|
||||||
|
|
||||||
|
### [Overview](/reference/additional/docs-app/overview)
|
||||||
|
|
||||||
|
General information about the Docs apps.
|
||||||
|
|
||||||
|
### [File Format](/reference/additional/docs-app/file-format)
|
||||||
|
|
||||||
|
Information about marks supported by the Docs app.
|
||||||
|
|
||||||
|
### [Index File](/reference/additional/docs-app/index-file)
|
||||||
|
|
||||||
|
Details of the `.toc` index file format.
|
||||||
|
|
||||||
|
### [Suggested Structure](/reference/additional/docs-app/structure)
|
||||||
|
|
||||||
|
Suggestions about how to structure docs.
|
161
content/reference/additional/docs-app/file-format.md
Normal file
161
content/reference/additional/docs-app/file-format.md
Normal file
@ -0,0 +1,161 @@
|
|||||||
|
+++
|
||||||
|
title = "File Format"
|
||||||
|
weight = 5
|
||||||
|
template = "doc.html"
|
||||||
|
+++
|
||||||
|
|
||||||
|
## `%docu` mark
|
||||||
|
|
||||||
|
{% callout %}
|
||||||
|
**Note**: this section is mostly useful if you're writing a mark conversion
|
||||||
|
method. For marks that are already supported and you can use directly, see
|
||||||
|
further down this page.
|
||||||
|
{% /callout %}
|
||||||
|
|
||||||
|
The `%docs` app supports any mark, as long as it has a conversion method to its
|
||||||
|
`%docu` mark. The `%docu` mark is not expected to be used directly to write
|
||||||
|
documentation, its purpose is to be a mark conversion target.
|
||||||
|
|
||||||
|
The `%docu` mark expects a `$manx`.
|
||||||
|
|
||||||
|
A `$manx` is how an XML node structure is represented in hoon. See [Section
|
||||||
|
5e](/reference/hoon/stdlib/5e#manx) of the standard library reference for
|
||||||
|
details. A `$manx` is what `++de-xml:html` and `++en-xml:html` decode/encode
|
||||||
|
raw XML strings from/to.
|
||||||
|
|
||||||
|
The `%docu` mark will technically accept any `$manx`, but the `%docs` agent
|
||||||
|
itself makes some changes and imposes some additional rules:
|
||||||
|
|
||||||
|
- The root element must be a `<div>`.
|
||||||
|
- `<h1>`, `<h2>`, and `<h3>` elements that are direct children of the root
|
||||||
|
`<div>` will be used to make the table of contents. Other header levels
|
||||||
|
will not be included in the table of contents, but they can still be used.
|
||||||
|
`<h1>`, through `<h3>` can also be used at deeper levels, but they also
|
||||||
|
won't be included in the table of contents.
|
||||||
|
- Only these tags are allowed: `<a>`, `<address>`, `<b>`, `<br>`,
|
||||||
|
`<blockquote>`, `<code>`, `<del>`, `<div>`, `<em>`, `<h1>`, `<h2>`, `<h3>`,
|
||||||
|
`<h4>`, `<h5>`, `<h6>`, `<hr>`, `<i>`, `<img>`, `<ins>`, `<li>`, `<ol>`,
|
||||||
|
`<p>`, `<pre>`, `<q>`, `<small>`, `<span>`, `<strong>`, `<sub>`, `<sup>`,
|
||||||
|
`<time>`, `<ul>`, `<var>`.
|
||||||
|
- Inside the `<h1>`, `<h2>`, and `<h3>` headers that are direct children of the
|
||||||
|
root `<div>` (and will therefore be used in the table of contents), only a
|
||||||
|
subset of the tags listed above are allowed: `<b>`, `<code>`, `<del>`, `<em>`,
|
||||||
|
`<i>`, `<ins>`, `<q>`, `<small>`, `<span>`, `<strong>`, `<sub>`, `<sup>`,
|
||||||
|
`<time>`, `<var>`.
|
||||||
|
- All attributes will be stripped from all elements (you can still include them
|
||||||
|
but they'll be removed), with the following exceptions:
|
||||||
|
- The `src` and `alt` attributes in an `<img>` tag.
|
||||||
|
- The `href` attribute in an `<a>` tag.
|
||||||
|
- A `class` attribute in a `<pre>` tag beginning with `language-` (e.g.
|
||||||
|
`class="language-hoon"`). This is not currently used for anything but will be used
|
||||||
|
for syntax highlighting in the future.
|
||||||
|
|
||||||
|
{% callout %}
|
||||||
|
**Note**: table elements are not currently supported but will likely be added
|
||||||
|
in a future release.
|
||||||
|
{% /callout %}
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Included marks
|
||||||
|
|
||||||
|
The following marks are supported by the %docs app and you can use them to
|
||||||
|
write docs right away.
|
||||||
|
|
||||||
|
### `%udon`
|
||||||
|
|
||||||
|
Udon is a markdown-like language native to hoon, with a parser built into the
|
||||||
|
hoon compiler. Here is its syntax in brief:
|
||||||
|
|
||||||
|
- The first line of the `.udon` document **must** be a single rune: `;>`.
|
||||||
|
This tells the compiler to interpret everything following as udon.
|
||||||
|
- **Paragraphs**: Content on a single line will be made into a paragraph. Paragraphs
|
||||||
|
may be hard-wrapped, so consecutive lines of text will become a single
|
||||||
|
paragraph. The paragraph will be ended by an empty line or other block
|
||||||
|
element.
|
||||||
|
- **Headers**: lines beginning with 1-6 `#`s followed by a single space and then
|
||||||
|
some content (e.g. `## foo`) will be made into headers. The number of `#`s
|
||||||
|
dictates the header level.
|
||||||
|
- **Italics**: content wrapped in single `_`s (e.g. `_foo_`) will be made italic.
|
||||||
|
- **Bold**: content wrapped in single `*`s (e.g. `*foo*`) will be made bold.
|
||||||
|
- **Unordered lists**: lines beginning with `-` followed by a space will be made
|
||||||
|
into items in a list. List lines can be hard-wrapped, with two spaces
|
||||||
|
beginning each subsequent line to be included in the list. Lists can be nested
|
||||||
|
by indenting the `-`s a further two spaces for each level of nesting.
|
||||||
|
- **Ordered lists**: lines beginning with `+` followed by a space will be made into
|
||||||
|
ordered lists, and numbered in the order they appear. These have the same
|
||||||
|
wrapping and nesting logic as unordered lists.
|
||||||
|
- **Links**: this is standard markdown syntax: square bracks containing the display
|
||||||
|
content and then parentheses containing the URL, e.g.
|
||||||
|
`[foo](http://example.com)`. The URL may also be a relative link or an anchor
|
||||||
|
link.
|
||||||
|
- **Images**: this is also standard markdown; a link with an exclamation mark at the
|
||||||
|
beginning, e.g. `![foo](http://example.com/image.png)`. The square brackets
|
||||||
|
contain the alt-text and the the parentheses contain the image URL.
|
||||||
|
- **Inline code**: text wrapped in single backticks will be rendered verbatim in a
|
||||||
|
monospace font.
|
||||||
|
- **Fenced codeblocks**: Triple-backticks on their own line begin and end a
|
||||||
|
codeblock. All lines in between will be rendered verbatim in a monospace font.
|
||||||
|
Note that udon does not support a language specification after the opening
|
||||||
|
backticks like markdown does.
|
||||||
|
- **Horizontal rules**: Three or more hyphens (`---`) will create a horizontal rule.
|
||||||
|
- **Block quotes**: a line beginning with `>` creates a block quote. This may be
|
||||||
|
hard-wrapped, as long as the next line is indented two spaces. Block quotes
|
||||||
|
may contain anything, including other blockquotes.
|
||||||
|
- **Line breaks**: A line ending in a single backslash will have a line break
|
||||||
|
inserted at the end, so it will not flow together with the subsequent line as
|
||||||
|
is usually the case.
|
||||||
|
- **Escape characters**: You may prefix Udon syntax with a backslash to have it
|
||||||
|
treated as the literal text.
|
||||||
|
- **Hoon constants**: Udon will automatically render any values with atom aura
|
||||||
|
syntax as inline code. It'll also render arms like `++foo:bar`, `+$baz`, and
|
||||||
|
`+*foo:bar:baz`, as inline code.
|
||||||
|
- **Sail**: this is hoon's native XML syntax. Udon will parse it, execute it, and
|
||||||
|
include the `+$manx`es produced in the resulting document. This means you
|
||||||
|
can embed arbitrary hoon in the document. There is little formal sail
|
||||||
|
documentation, but you can refer to the [`;` (mic) rune
|
||||||
|
reference](/reference/hoon/rune/mic) for most of its runes and some
|
||||||
|
rudimentary examples.
|
||||||
|
|
||||||
|
{% callout %}
|
||||||
|
**Note**: Udon is quite strict on its syntax, and may fail to parse if it's
|
||||||
|
incorrect.
|
||||||
|
{% /callout %}
|
||||||
|
|
||||||
|
### `%txt`
|
||||||
|
|
||||||
|
The `%docs` app supports plain `.txt` files. The file will be rendered as a
|
||||||
|
preformatted codeblock with wrapping.
|
||||||
|
|
||||||
|
### `%html`
|
||||||
|
|
||||||
|
Ordinary HTML files may be used, but note the tag and structural restrictions
|
||||||
|
described in the `%docu` mark description above.
|
||||||
|
|
||||||
|
### `%gmi`
|
||||||
|
|
||||||
|
|
||||||
|
Gemtext is an ultra-minimal markup format developed for the [Gemini
|
||||||
|
project](https://gemini.circumlunar.space/), an internet protocol for serving
|
||||||
|
light-weight hypertext, inspired by Gopher. Its file extension is `.gmi`.
|
||||||
|
|
||||||
|
Gemtext interprets things on a line-by-line basis, and does not support
|
||||||
|
different types on a single line. Every line is a separate element, with the
|
||||||
|
exception of fenced codeblocks which may span multiple lines. In brief, here is
|
||||||
|
the syntax:
|
||||||
|
|
||||||
|
- **Paragraphs**: Plain text on a single line constitutes a paragraph. Note
|
||||||
|
hard-wrapping is not supported.
|
||||||
|
- **Links**: lines beginning with `=>` followed by a space create a link. After the
|
||||||
|
space, the target URL is given. After the URL, there may optionally be a space
|
||||||
|
and then some display text for the link. If no displace text is given, the URL
|
||||||
|
itself will be displayed.
|
||||||
|
- **Codeblocks**: triple-backticks at the beginning of a line begin and end a
|
||||||
|
codeblock. All text in between will be rendered verbatim in a monospace font.
|
||||||
|
The opening backticks may optionally be followed by some text, which will be
|
||||||
|
used as the language tag.
|
||||||
|
- **Headings**: 1-3 `#`s followed by text create a heading. The number of `#`s
|
||||||
|
determine the heading level.
|
||||||
|
- **Lists**: lines beginning with `*` followed by a space and then text will create
|
||||||
|
a list item.
|
||||||
|
- **Quotes**: lines beginning with `>` followed by a space creates a blockquote.
|
45
content/reference/additional/docs-app/index-file.md
Normal file
45
content/reference/additional/docs-app/index-file.md
Normal file
@ -0,0 +1,45 @@
|
|||||||
|
+++
|
||||||
|
title = "Index File"
|
||||||
|
weight = 10
|
||||||
|
template = "doc.html"
|
||||||
|
+++
|
||||||
|
|
||||||
|
Each desk with docs may include a `doc.toc` file in its root. A `doc.toc` file
|
||||||
|
looks something like this:
|
||||||
|
|
||||||
|
```
|
||||||
|
/dev Developer
|
||||||
|
/hark-store Hark-store
|
||||||
|
/overview/udon Overview
|
||||||
|
/types/udon Data Types
|
||||||
|
/pokes/udon Pokes
|
||||||
|
/paths/udon Subscription Paths
|
||||||
|
/scry/udon Scry Endpoints
|
||||||
|
/settings-store Settings-store
|
||||||
|
/overview/udon Overview
|
||||||
|
/types/udon Data Types
|
||||||
|
/pokes/udon Pokes
|
||||||
|
/paths/udon Subscription Paths
|
||||||
|
/scry/udon Scry Endpoints
|
||||||
|
```
|
||||||
|
|
||||||
|
Each line contains a pair of path and title with at least one space in between.
|
||||||
|
A path with a single element (such as `/dev` and `/hark-store`) denotes a
|
||||||
|
directory. A path with two elements (such as `/overview/udon`) denotes a file,
|
||||||
|
where the first element is the name and the second is the mark.
|
||||||
|
|
||||||
|
Any directory structure and depth is allowed. The hierarchy is determined by
|
||||||
|
indentation. Each double-space indent denotes a nesting level. Two spaces is one
|
||||||
|
level, four spaces is two levels, etc.
|
||||||
|
|
||||||
|
The root is the `/doc` directory of your desk, it should not be explicitly
|
||||||
|
listed.
|
||||||
|
|
||||||
|
The title specified will be displayed at the top of the document and in the
|
||||||
|
table of contents for the desk.
|
||||||
|
|
||||||
|
If no `doc.toc` file is included, but a desk does have other files under
|
||||||
|
`/doc`, the Docs app will infer a table of contents from the directory
|
||||||
|
structure, and _all_ files will be included. Files are ordered alphabetically,
|
||||||
|
except that 'overview' always come first. For titles, hyphens in the filename
|
||||||
|
are replaced with spaces and the whole is converted to Title Case.
|
47
content/reference/additional/docs-app/overview.md
Normal file
47
content/reference/additional/docs-app/overview.md
Normal file
@ -0,0 +1,47 @@
|
|||||||
|
+++
|
||||||
|
title = "Overview"
|
||||||
|
weight = 1
|
||||||
|
template = "doc.html"
|
||||||
|
+++
|
||||||
|
|
||||||
|
The `%docs` app allows you to include documentation with the desks you
|
||||||
|
distribute, making them available for easy browsing by users and developers.
|
||||||
|
|
||||||
|
The `%docs` app will automatically detect and publish any docs included with
|
||||||
|
any installed desks. As long as they're in the correct place and of a filetype
|
||||||
|
with appropriate `mark` conversion methods, they'll be picked up.
|
||||||
|
|
||||||
|
A `doc.toc` file may be included in the root of the desk, specifying the files
|
||||||
|
to be included, their `mark`s, and their titles. See the [Index
|
||||||
|
File](/reference/additional/docs-app/index-file) section for details.
|
||||||
|
|
||||||
|
The files will be in a `/doc` directory in the root of the desk. They may be of
|
||||||
|
any filetype, as long as it has conversion methods to the `%docu` mark used by
|
||||||
|
the `%docs` app. The `%docs` app includes parsers and conversion methods for
|
||||||
|
the following marks by default:
|
||||||
|
|
||||||
|
- `%txt` - Ordinary `.txt` text files.
|
||||||
|
- `%udon` - A markdown-like format that supports embedded hoon.
|
||||||
|
- `%gmi` - An ultra-minimalist markup format called "gemtext".
|
||||||
|
- `%html` - An ordinary `.html` file.
|
||||||
|
|
||||||
|
For more details of these file formats, as well as details of the `%docu` mark
|
||||||
|
and other format requirements of the `%docs` app, see the [File
|
||||||
|
Format](/reference/additional/docs-app/file-format) section.
|
||||||
|
|
||||||
|
Apart from the `mark` and location requirements described above, there are no
|
||||||
|
particular restrictions on how you organise your docs, or what docs you
|
||||||
|
include. There are, however, some general recommendations detailed in the
|
||||||
|
[Suggested Structure](/reference/additional/docs-app/structure) section.
|
||||||
|
|
||||||
|
## Dev desk
|
||||||
|
|
||||||
|
To include docs in your own desk, there are a few files you'll need (mark
|
||||||
|
files, etc). These are included in the `docs-dev` dev desk in the [github
|
||||||
|
repo](https://github.com/tinnus-napbus/docs-app). These files are all
|
||||||
|
symlinked, so you'll need to clone the whole repo, then copy them across with
|
||||||
|
something like:
|
||||||
|
|
||||||
|
```
|
||||||
|
cp -rL git/docs-app/docs-dev/* /path/to/your/development/desk
|
||||||
|
```
|
91
content/reference/additional/docs-app/structure.md
Normal file
91
content/reference/additional/docs-app/structure.md
Normal file
@ -0,0 +1,91 @@
|
|||||||
|
+++
|
||||||
|
title = "Suggested Structure"
|
||||||
|
weight = 15
|
||||||
|
template = "doc.html"
|
||||||
|
+++
|
||||||
|
|
||||||
|
Here we'll discuss recommendations and best practices for your docs. The
|
||||||
|
%docs app doesn't impose any restrictions on the structure of your docs, so
|
||||||
|
you're free to do things differently if you feel it's appropriate.
|
||||||
|
|
||||||
|
## User docs
|
||||||
|
|
||||||
|
For the most part, user documentation depends on the nature of your app, so it's
|
||||||
|
up to you how you document it. There are, however, a couple of things that are
|
||||||
|
advisable to include:
|
||||||
|
|
||||||
|
### General info
|
||||||
|
|
||||||
|
You should include some of the following information (as appropriate) in either
|
||||||
|
a distinct informational document or at the top of the first document:
|
||||||
|
|
||||||
|
- **Publisher/developer/contributors**: Your `@p`, the `@p` you distribute the app
|
||||||
|
from, people who have helped build the app, etc.
|
||||||
|
- **License**: MIT, GPL, etc.
|
||||||
|
- **Source**: Github link (or similar) for the repo containing the source code.
|
||||||
|
- **Issues**: Where to file issues (typically also the Github repo).
|
||||||
|
- **Group**: If you have a group associated with your app (for support, discussion,
|
||||||
|
or what have you), you can include the `~host/group-name`.
|
||||||
|
- Any other metadata, links, info, etc, you feel are appropriate to include.
|
||||||
|
|
||||||
|
### Changelog
|
||||||
|
|
||||||
|
Another useful document is a changelog. For each version you release, you can
|
||||||
|
add a new section at the top with the version number, release date, and a brief
|
||||||
|
summary of the changes.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Developer docs
|
||||||
|
|
||||||
|
Like user docs, you're free to document things as you see fit, but it's helpful
|
||||||
|
to include particular things with a standard format. These are documented
|
||||||
|
below.
|
||||||
|
|
||||||
|
{% callout %}
|
||||||
|
**Note**: If your desk has a dev version, it's advisable to link to it
|
||||||
|
somewhere sensible in the developer documentation.
|
||||||
|
{% /callout %}
|
||||||
|
|
||||||
|
### API Reference
|
||||||
|
|
||||||
|
If there's any chance other developers will want to interface with agents on
|
||||||
|
your desk, you should include reference information about the scry endpoints,
|
||||||
|
pokes, subscription paths, and (if appropriate) data types of each agent.
|
||||||
|
|
||||||
|
These things can either be on a single page, or each have their own separate
|
||||||
|
page, depending on their complexity.
|
||||||
|
|
||||||
|
#### Scry endpoints
|
||||||
|
|
||||||
|
Scry endpoints may either be organised by their paths or by short summaries of
|
||||||
|
each endpoint's purpose. Scry paths should be in the format
|
||||||
|
`/[care]/rest/of/path`, like `/x/foo/bar`. Any variable parts of the scry path
|
||||||
|
should have square brackets like `/x/foo/[ship]`. The data type of the response
|
||||||
|
should be specified, and it's helpful to include an example of a scry and the
|
||||||
|
pretty-printed response in a codeblock.
|
||||||
|
|
||||||
|
#### Pokes
|
||||||
|
|
||||||
|
Any poke actions an agent will accept should be documented. It's helpful to
|
||||||
|
include an example poke. You may also wish to provide a JSON example if people
|
||||||
|
can interact with your agent through Eyre's channel system or similar.
|
||||||
|
|
||||||
|
If your agent's pokes are organised around something like an "action" tagged
|
||||||
|
union structure, the poke reference might work better as a kind of data type
|
||||||
|
reference for that action structure rather than specifically pokes.
|
||||||
|
|
||||||
|
#### Subscriptions
|
||||||
|
|
||||||
|
Subscription paths should be documented in a similar manner to the scry
|
||||||
|
reference. If the updates your agent can send out to subscribers are organised
|
||||||
|
around something like an "update" tagged union structure, the subscription
|
||||||
|
reference might work better as just a brief path reference, and documentation of
|
||||||
|
the updates can be done separately.
|
||||||
|
|
||||||
|
#### Data types
|
||||||
|
|
||||||
|
The inclusion of a data types section depends on the complexity of an agent's
|
||||||
|
data types. If such a reference is appropriate, it's best to structure it with a
|
||||||
|
separate section for each type. The type definition should be included in a
|
||||||
|
codeblock, as well as a brief description of its purpose.
|
Loading…
Reference in New Issue
Block a user