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

Generate Documentation #13

Open
paf31 opened this issue Oct 16, 2016 · 5 comments

Comments

@paf31
Copy link
Member

commented Oct 16, 2016

Since all packages in a set will build together, it makes sense to generate all documentation at once, so that we can show things like links to instances in other modules.

We should probably think about how this applies to Pursuit in the longer term if the psc-package experiment is a success

@hdgarrood, any thoughts? I think we could potentially aim to have Pursuit build docs on a regular basis for each active package set, or something like that. Since we would build and cache all externs for a package set during CI anyway, we could use this to get a pretty great type search feature too.

@hdgarrood

This comment has been minimized.

Copy link
Member

commented Oct 16, 2016

I feel like I've been out of the loop for quite a while so I'm not sure really how helpful I can be on this front, but this does sound very exciting to me; I'd certainly welcome work in this direction. In particular I can't think of any reasons not to at least attempt this.

@f-f

This comment has been minimized.

Copy link
Collaborator

commented Feb 27, 2019

All of this is being tracked in this Spago issue as well: spacchetti/spago#89

I'll close this one as the linked issue has much more detail and an implementation plan (as this will need support from spago or psc-package and some compiler work too), so please refer to that one

@f-f f-f closed this Feb 27, 2019
@f-f

This comment has been minimized.

Copy link
Collaborator

commented Aug 29, 2019

I'm going to revive this issue to retarget it toward generating "Pursuit-like" documentation for every release of this repo.

Since spago-0.9.0 it is now possible to have a client-side search field added to the HTML docs generated by the compiler (thanks to the great work in purescript-docs-search).
This means that we could generate static html documentation from CI for every release of this repo.

How I'd do it (all of this would happen on release CI):

  • create an ephemeral spago project with all the packages in the set as dependencies (we can do this easily by downloading the release with dhall-json and templating a spago.dhall with the resulting list)
  • run spago docs
  • move the result to a folder with the release name
  • commit it to the gh-pages branch

In this way we'd get the docs at something like https://purescript.github.io/package-sets/whatever-release-name

Some additional points:

  • we might want some index.html to index all releases (much like the homepage for Stackage)
  • we might want to not point to the GitHub Pages URL directly, but instead use something like package-sets.purescript.org, so that if the documentation starts taking too much disk space we can move off GitHub easily without breaking anyone's workflow
@f-f f-f reopened this Aug 29, 2019
@f-f

This comment has been minimized.

Copy link
Collaborator

commented Aug 29, 2019

Update: @klntsky is working on this, you can find the work in progress at https://github.com/spacchetti/starsuit

@klntsky

This comment has been minimized.

Copy link
Contributor

commented Aug 29, 2019

Yep, and the docs in their current state can be found here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
4 participants
You can’t perform that action at this time.