Skip to content

Commit

Permalink
Move API docs higher up on the landing page (foxglove#426)
Browse files Browse the repository at this point in the history 
* Move relevant API docs higher up the page by using columns for features and moving concepts down to the resources section; Add nav links to docs at top; Add resource links
  • Loading branch information
@esthersweon
esthersweon committed Jun 16, 2022
1 parent 3e7ac5b commit cfea5a5
Show file tree
Hide file tree
Showing 2 changed files with 171 additions and 73 deletions.
205 changes: 133 additions & 72 deletions docs/website/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,104 +17,136 @@
</head>
<body>
<div class="max-w-3xl mx-auto">
<h1 class="mb-4 text-center font-bold text-4xl md:text-5xl">
<nav class="nav-links links">
<a href="https://github.com/foxglove/mcap/tree/main/go/cli/mcap"
><code>mcap</code> CLI</a
>
<a href="https://mcap.dev/docs/cpp/">For C++</a>
<a href="https://mcap.dev/docs/python/">For Python</a>
<a href="https://mcap.dev/docs/typescript/">For TypeScript</a>
<a href="https://pkg.go.dev/github.com/foxglove/mcap/go/mcap">For Go</a>
<a href="https://mcap.dev/docs/swift/documentation/mcap/">For Swift</a>
</nav>

<h1 class="mt-8 mb-4 text-center font-bold text-4xl md:text-5xl">
<img src="mcap.png" alt="" class="inline-block h-16" />
<a href="https://github.com/foxglove/mcap">MCAP</a>
</h1>

<p>
MCAP (pronounced "em-cap") is a modular container file format for
heterogeneous timestamped data. It is ideal for robotics applications,
as it can record multiple streams of structured and unstructured data in
a single file.
as it can record multiple streams of structured and unstructured data
(e.g. <a href="https://ros.org">ROS</a>,
<a href="https://developers.google.com/protocol-buffers">Protobuf</a>,
<a href="https://json-schema.org/">JSON Schema</a>,
<a href="https://msgpack.org/index.html">MessagePack</a>, etc.) in a
single file.
</p>

<p>
MCAP works well under various workloads, resource constraints, and
durability requirements.
</p>

<h2>Concepts</h2>
<dl class="glossary">
<div>
<dt>Message</dt>
<dd>
The unit of communication between nodes in the pub/sub system.
</dd>
</div>
<div>
<dt>Channel</dt>
<dd>
A stream of messages which have the same type, or schema. Often
corresponds to a connection between a publisher and a subscriber.
</dd>
</div>
<div>
<dt>Schema</dt>
<dd>
A description of the structure and contents of messages on a
channel, e.g. a
<a
href="https://developers.google.com/protocol-buffers/docs/techniques#self-description"
>Protobuf <code>FileDescriptorSet</code></a
>
or <a href="https://json-schema.org">JSON Schema</a>.
</dd>
</div>
</dl>

<dl class="features">
<h2>Features</h2>
<ul>
<li>
<b>Supports heterogeneous data</b>
<div class="row">
<div class="col">
<svg
xmlns="http://www.w3.org/2000/svg"
class="h-6 w-6"
fill="none"
viewBox="0 0 24 24"
stroke="currentColor"
stroke-width="2"
>
<path
stroke-linecap="round"
stroke-linejoin="round"
d="M4 5a1 1 0 011-1h14a1 1 0 011 1v2a1 1 0 01-1 1H5a1 1 0 01-1-1V5zM4 13a1 1 0 011-1h6a1 1 0 011 1v6a1 1 0 01-1 1H5a1 1 0 01-1-1v-6zM16 13a1 1 0 011-1h2a1 1 0 011 1v6a1 1 0 01-1 1h-2a1 1 0 01-1-1v-6z"
/>
</svg>
<h3 class="header">Heterogeneous data</h3>
<ul>
<li>
Store messages encoded in a variety of serialization formats
(e.g. ROS, Protobuf, JSON Schema, MessagePack, etc.) in a single
file
</li>
<li>
Can include metadata and attachments with application-specific
data
Store messages encoded in multiple serialization formats in a
single file
</li>
<li>Include metadata and attachments</li>
</ul>
</li>
<li>
<b>Optimized for high-performance writing</b>
</div>

<div class="col">
<svg
xmlns="http://www.w3.org/2000/svg"
class="h-6 w-6"
fill="none"
viewBox="0 0 24 24"
stroke="currentColor"
stroke-width="2"
>
<path
stroke-linecap="round"
stroke-linejoin="round"
d="M15.232 5.232l3.536 3.536m-2.036-5.036a2.5 2.5 0 113.536 3.536L6.5 21.036H3v-3.572L16.732 3.732z"
/>
</svg>
<h3 class="header">Performant writing</h3>
<ul>
<li>Append-only structure</li>
<li>
Recover partially-written files, even when data recording is
Recover partially-written files when data recording is
interrupted
</li>
</ul>
</li>
<li>
<b>Efficient reading and seeking within files</b>
<ul>
<li>
Use indexing to extract data without scanning the entire file,
even over remote connections
</li>
<li>Fast access to summary data</li>
</ul>
</li>
<li>
<b>Self-contained</b>
</div>
</div>

<div class="row">
<div class="col">
<svg
xmlns="http://www.w3.org/2000/svg"
class="h-6 w-6"
fill="none"
viewBox="0 0 24 24"
stroke="currentColor"
stroke-width="2"
>
<path
stroke-linecap="round"
stroke-linejoin="round"
d="M8 7h12m0 0l-4-4m4 4l-4 4m0 6H4m0 0l4 4m-4-4l4-4"
/>
</svg>
<h3 class="header">Efficient seeking</h3>
<ul>
<li>Embedded message schemas</li>
<li>No additional dependencies required for decoding</li>
<li>Extract data without scanning the entire file</li>
<li>Fast access to indexed summary data</li>
</ul>
</li>
<li>
<b>Reliable under various limitations</b>
</div>

<div class="col">
<svg
xmlns="http://www.w3.org/2000/svg"
class="h-6 w-6"
fill="none"
viewBox="0 0 24 24"
stroke="currentColor"
stroke-width="2"
>
<path
stroke-linecap="round"
stroke-linejoin="round"
d="M5 8h14M5 8a2 2 0 110-4h14a2 2 0 110 4M5 8v10a2 2 0 002 2h10a2 2 0 002-2V8m-9 4h4"
/>
</svg>
<h3 class="header">Self-contained files</h3>
<ul>
<li>Workload sizes</li>
<li>Resource constraints</li>
<li>Durability requirements</li>
<li>Embed all message schemas in the file</li>
<li>No extra dependencies needed for decoding</li>
</ul>
</li>
</ul>
</div>
</div>
</dl>

<dl class="quick-start">
Expand Down Expand Up @@ -148,9 +180,38 @@ <h2>Quick start</h2>
<a href="https://mcap.dev/docs/swift/documentation/mcap/">Swift</a>
</nav>
</dl>

<dl class="resources">
<h2>Resources</h2>
<p>To learn more about MCAP:</p>
<h2>Additional resources</h2>
<p>MCAP organizes its data via the following concepts:</p>
<dl class="glossary">
<div>
<dt>Message</dt>
<dd>
The unit of communication between nodes in the pub/sub system.
</dd>
</div>
<div>
<dt>Channel</dt>
<dd>
A stream of messages which have the same type, or schema. Often
corresponds to a connection between a publisher and a subscriber.
</dd>
</div>
<div>
<dt>Schema</dt>
<dd>
A description of the structure and contents of messages on a
channel, e.g. a
<a
href="https://developers.google.com/protocol-buffers/docs/techniques#self-description"
>Protobuf <code>FileDescriptorSet</code></a
>
or <a href="https://json-schema.org">JSON Schema</a>.
</dd>
</div>
</dl>
<p>Check out the resources below to learn more about MCAP:</p>
<nav>
<ul>
<li>
Expand Down
39 changes: 38 additions & 1 deletion docs/website/style.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@
}

.glossary {
@apply table m-8;
@apply table mt-4;
}
.glossary div {
@apply table-row;
Expand All @@ -57,6 +57,40 @@
@apply table-cell pb-2;
}

.nav-links {
display: flex;
justify-content: space-around;
margin-bottom: 2em;
}

.features {
@apply pt-4 flex flex-col flex-wrap;
font-size: 15px;
}

.features .row {
@apply flex flex-wrap flex-1;
}

.features .col {
@apply flex flex-col items-center flex-1 m-2 p-4;
min-width: 180px;
border: 1px solid gray;
border-radius: 5px;
}

.features .header {
@apply uppercase font-bold;
}

.features svg {
@apply mt-0 mx-auto mb-2 h-6 w-6;
}

.features li {
@apply mt-0;
}

.features ul,
.quick-start ul,
.resources ul {
Expand All @@ -74,6 +108,9 @@
.links a::after {
content: " →";
}
.nav-links a::after {
content: "";
}
.links a:hover {
@apply border-b-2;
}
Expand Down

0 comments on commit cfea5a5

Please sign in to comment.