Details
-
Type:
Story
-
Status: Done
-
Resolution: Done
-
Fix Version/s: None
-
Component/s: www_lsst_io
-
Labels:None
-
Story Points:5.5
-
Epic Link:
-
Team:SQuaRE
-
Urgent?:No
Description
www.lsst.io includes documents in the Algolia search index, but we haven't created ingest pipelines for user guides yet.
In the meantime, lets manually add links to these user guides from the homepage so that our documentation is more discoverable.
The guides can probably be maintained in a JSON file with Title, link, description fields, category, and "featured" fields. This data can be ingested via Gatsby data layer. On the homepage, we'll display these links in cards/grid.
Attachments
Activity
Gregory Dubois-Felsmann, the answer is yes, but the path isn't totally clear yet. I think my preference is to cross-publish the tutorial notebooks with Sphinx documentation, in which case they'll start to appear once we ingest user guides.
Summary of the solution:
User guides are listed in /src/data/guides.yaml. A single guide's object looks like this:
- slug: kafkit
|
title: Kafkit
|
github: lsst-sqre/kafkit
|
tags:
|
- org/dm
|
- system/efd
|
- system/roundtable
|
description: >
|
Kafkit helps you write Kafka producers and consumers in Python with asyncio.
|
Collections of guides are listed in /src/data/guideCollections.yaml. Collections are based on tags:
- title: Roundtable infrastructure documentation
|
slug: roundtable-guides
|
tag: system/roundtable
|
description: >
|
Developer and operational documentation for the Roundtable platform, and services that run on Roundtable. |
In gatsby-node.js we generate pages for each guide collection.
On the homepages, guides are presented in a "Featured guides" section and well as collections of guides in a "Guides" section (see screenshots).
Guide collection pages present individual guides in a grid.
Going beyond user guides: is there a long-term aspiration to make a core set of curated tutorial notebooks available through the central search system?