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

Add listing of user guides to www.lsst.io

    XMLWordPrintable

    Details

    • Type: Story
    • Status: Done
    • Resolution: Done
    • Fix Version/s: None
    • Component/s: www_lsst_io
    • Labels:
      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

          No builds found.
          jsick Jonathan Sick created issue -
          jsick Jonathan Sick made changes -
          Field Original Value New Value
          Epic Link DM-25248 [ 435569 ]
          Hide
          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?

          Show
          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?
          jsick Jonathan Sick made changes -
          Status To Do [ 10001 ] In Progress [ 3 ]
          Hide
          jsick Jonathan Sick added a comment -

          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.

          Show
          jsick Jonathan Sick added a comment - 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.
          jsick Jonathan Sick made changes -
          Story Points 5.5
          jsick Jonathan Sick made changes -
          Attachment Screenshot_2020-08-04 Home.png [ 45144 ]
          jsick Jonathan Sick made changes -
          Hide
          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.

          Show
          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.
          jsick Jonathan Sick made changes -
          Resolution Done [ 10000 ]
          Status In Progress [ 3 ] Done [ 10002 ]

            People

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

              Dates

              Created:
              Updated:
              Resolved:

                CI Builds

                No builds found.