Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create new Enso documentation viewer #8

Open
BinarySoftware opened this issue Feb 16, 2021 · 0 comments
Open

Create new Enso documentation viewer #8

BinarySoftware opened this issue Feb 16, 2021 · 0 comments
Assignees
Labels
Category: Appearance The appearance of the viewer Category: Build Build and deployment Category: Documentation Project documentation Category: Functionality The viewer functionality Change: Breaking A change that will break a public API or user-facing behaviour Difficulty: Core Contributor Should only be attempted by a core contributor Priority: Highest Should be completed ASAP Size: Large Requires a large time commitment Type: Enhancement An enhancement to Enso

Comments

@BinarySoftware
Copy link
Contributor

BinarySoftware commented Feb 16, 2021

Project summary

The public-facing documentation site will be a static site generated using a static site generator and hosted using GitHub Pages (or an alternative such as Netlify). The advantage of this is:

  • Low maintenance: the static site does not require maintaining any servers or provisioning any services on cloud hosting. There is no application to fail or update.
  • Speed: Serving static files is fast, there is no server side rendering or API requests to introduce performance overhead for a user.
  • GitOps: New content can be added and managed via typical development workflows, integrated with normal day-to-day dev work via GitHub actions.

The developer documentation site uses a version of this process. Whilst the devdoc site has some requirements that the public facing docs do not (low impact on the docs writers, aka developers), the process will be much the same.

To integrate the Standard Library documentation with such a static site, using the Javascript parser/generator, the suggested method would be:

  • A GitHub Action triggered on new release builds on github.com/enso-org/enso,
    That calls the JS parser on the standard library files, parsing the included doc comments,
    Generates static output, either HTML or markdown,
    And pushes the resulting files to another repository that serves as the source for the end static site.
@BinarySoftware BinarySoftware self-assigned this Feb 16, 2021
@BinarySoftware BinarySoftware added Category: Documentation Project documentation Category: Generator Change: Breaking A change that will break a public API or user-facing behaviour Difficulty: Intermediate Some prior knowledge required Priority: High Should be completed in the next sprint Type: Enhancement An enhancement to Enso labels Feb 18, 2021
@BinarySoftware BinarySoftware added Category: Appearance The appearance of the viewer Category: Build Build and deployment Category: Functionality The viewer functionality Difficulty: Core Contributor Should only be attempted by a core contributor Priority: Highest Should be completed ASAP Size: Large Requires a large time commitment and removed Difficulty: Intermediate Some prior knowledge required Priority: High Should be completed in the next sprint labels Feb 24, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Category: Appearance The appearance of the viewer Category: Build Build and deployment Category: Documentation Project documentation Category: Functionality The viewer functionality Change: Breaking A change that will break a public API or user-facing behaviour Difficulty: Core Contributor Should only be attempted by a core contributor Priority: Highest Should be completed ASAP Size: Large Requires a large time commitment Type: Enhancement An enhancement to Enso
Projects
None yet
Development

No branches or pull requests

1 participant