Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-25918

Add listing of user guides to www.lsst.io

    XMLWordPrintable

Details

    • Story
    • Status: Done
    • Resolution: Done
    • None
    • www_lsst_io
    • None

    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

          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?

          gpdf Gregory Dubois-Felsmann added a comment - 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?

          gpdf, 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.

          jsick Jonathan Sick added a comment - gpdf , 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.

          jsick Jonathan Sick added a comment - 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.

          People

            jsick Jonathan Sick
            jsick Jonathan Sick
            Gregory Dubois-Felsmann, Jonathan Sick
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved:

              Jenkins

                No builds found.