mirror of
https://github.com/urbit/developers.urbit.org.git
synced 2024-08-16 09:10:48 +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"
|
||||
weight = 900
|
||||
weight = 90
|
||||
sort_by = "weight"
|
||||
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