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.

Sign up for GitHub

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

Jump to bottom

fix publish workflow #1078

Merged
merged 8 commits into from
Oct 22, 2021
Merged

fix publish workflow #1078

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
ba24e2e
fix publish workflow
i10416 Oct 18, 2021
b849bf6
fix condition
i10416 Oct 19, 2021
ffa5234
move api documentation url
i10416 Oct 20, 2021
3e14896
small fix
i10416 Oct 20, 2021
ec48161
use mdoc variable
i10416 Oct 20, 2021
bd4abe9
replace travis badge with github actions one
i10416 Oct 20, 2021
7b9e502
resolve conflict
i10416 Oct 20, 2021
0ad028b
small fix
i10416 Oct 20, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions .github/workflows/publish_microsite.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
name: Publish Doc

on:
push:
branches:
- main
paths:
- docs/**

jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout current branch
uses: actions/checkout@v2
with:
fetch-depth: 0
- name: Setup Jekyll
run: |
gem install --install-dir $HOME/vendor/bundle jekyll
echo "GEM_HOME=$HOME/vendor/bundle" >> $GITHUB_ENV
echo "GEM_PATH=$HOME/vendor/bundle" >> $GITHUB_ENV
echo "$HOME/vendor/bundle/bin" >> $GITHUB_PATH
- name: Build docs
run: |
sbt docs/makeMicrosite
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where does sbt come from? I think you usually need to install it with an action.

Instead of as a hand-written workflow, Do you think we can include this in the sbt build with sbt-gh-actions? Then most of the setup and compiling is done automatically. See e.g. https://github.com/typelevel/fs2/blob/main/build.sbt#L349

Thanks!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where does sbt come from?

ubuntu-latest has sbt installed.

Copy link
Contributor Author

@i10416 i10416 Oct 19, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@armanbilge

I choose a hand-written workflow because I have one concern. Is it possible for sbt-gh-actions to define multiple workflow

It is faster to publish docs when we use multiple workflows because workflow runs in parallel but steps do not run in parallel.

Copy link
Contributor Author

@i10416 i10416 Oct 19, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I missed the e.g. link.

Copy link
Contributor Author

@i10416 i10416 Oct 19, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@armanbilge

Do you think we can include this in the sbt build

Answer is "yes, we can" but do we really need that?

I think hand-written workflow is better when it comes to managing spire document because

  • current publish task has little to do with Scala(only mdoc task), it is done by jekyll and actions-gh-pages. Wrapping them in sbt task does not seem straightforward.
  • I took a look sbt-gh-actions and sbt-gh-actions focus mainly on making it easier to test, build and publish Scala sources over cross java/scala versions and cross target platforms(jvm/native/js) (though it is possible to add publish docs jobs).
    • In addition, if we include publish task in jobs, we have to introduce another action to detect file changes, which can be done by github workflow's path filter.
  • some libraries in typelevel repo like cats-effect uses hand-written workflow for publishing docs. https://github.com/typelevel/cats-effect/blob/docs/.github/workflows/microsite.yml
  • publish docs workflow has a lifecycle different from CI workflow. Ci should run every PR or commit in order to validate changes, but publish docs workflow should run when microsite actually changes. They are different concern.
  • separating document settings from build settings will keep build settings simple(and makes it easier to migrate to another document tools in the future.)

You say "setup and compiling is done automatically" but these features make little difference for publishing docs. We do not have to setup Java or Scala for publishing docs. We need setup jekyll, envs and paths even if we use sbt-gh-actions.

If we would publish docs for each spire versions over each Scala versions and each platforms it would be worth managing it in build.sbt, but current microsite is independent of Scala versions or platforms, just displaying information of the latest version, so the publish doc workflow is simple enough and will not be likely to swell further.

Copy link
Member

@armanbilge armanbilge Oct 19, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@i10416 thanks for the detailed research and write-up, this is great.

We do not have to setup Java or Scala for publishing docs.

Yes, this was my faulty assumption. Sorry about that.

publish docs workflow has a lifecycle different from CI workflow. Ci should run every PR or commit in order to validate changes, but publish docs workflow should run when microsite actually changes. They are different concern.

That's true, but we should build the docs as part of CI for PRs to make sure the PR didn't break the documentation somehow. E.g. maybe an example in the docs is using some code that changed, etc.

In addition, if we include publish task in jobs, we have to introduce another action to detect file changes, which can be done by github workflow's path filter.

IIUC publishing the docs also publishes the API docs: http://typelevel.org/spire/api/spire/index.html
If it doesn't, then it should. This can change even when there haven't been changes in the docs folder. So we should actually be careful to only publish the site when we release a new, stable version, I think, so that the docs don't get mismatched?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, you mean you want to programatically garantee docs are successfully built using 'if ....' or 'needs build' ? If so, it would be better to include the doc job in build.sbt.

Sorry, I assumed that docs are supposed to be successfully built everytime PR is merged to main (or version tag is set) because current workflow contains build docs step and you can be sure docs are vaild.

So we should actually be careful to only publish the site when we release a new, stable version

Ok, workflow becomes simpler and there's no need to check doc file changes as publishing documents happens only when stable release, not when doc files changes.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@armanbilge

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, just for my own clarification the docs should be built as part of every PR, to avoid breaking something. And as you point out, they already are. But of course, they should not be published from the PR :)

Ok, workflow becomes simpler and there's no need to check doc file changes as publishing documents happens only when stable release, not when doc files changes.

The downside to this is that docs contributions/updates are not published until the next release ... but, it prevents the API docs from getting out of sync with the published artifact, which could be very confusing. I'm open to ideas to improve this.

One way would be to publish the API docs under a version directory (e.g., 0.17, 0.18, SNAPSHOT). So this way, even though updating the site would also update the API docs, it would publish under SNAPSHOT instead of overwriting the API docs for the current.

For clarification, I'm distinguishing between the site/main docs (which should ideally be updated as frequently as possible) and the API docs aka scaladocs, which should match the published artifact.

Thoughts? Thanks again for your help with this, much appreciated!

- name: publish
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs/target/site
publish_branch: gh-pages
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
[![Build Status](https://api.travis-ci.org/typelevel/spire.png)](https://travis-ci.org/typelevel/spire/)
[![Continuous Integration](https://github.com/typelevel/spire/actions/workflows/ci.yml/badge.svg)](https://github.com/typelevel/spire/actions/workflows/ci.yml)
[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/typelevel/spire?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![codecov.io](http://codecov.io/github/typelevel/spire/coverage.svg?branch=main)](http://codecov.io/github/typelevel/spire?branch=main)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.typelevel/spire_2.12/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.typelevel/spire_2.11)
Expand Down
17 changes: 11 additions & 6 deletions build.sbt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,19 +50,19 @@ inThisBuild(
List(
organization := "org.typelevel",
homepage := Some(url("https://typelevel.org/spire/")),
licenses += ("MIT", url("http://opensource.org/licenses/MIT")),
licenses += ("MIT", url("https://opensource.org/licenses/MIT")),
developers := List(
Developer(
"id_m",
"Erik Osheim",
"",
url("http://github.com/non/")
url("https://github.com/non/")
),
Developer(
"tixxit",
"Tom Switzer",
"",
url("http://github.com/tixxit/")
url("https://github.com/tixxit/")
)
)
)
Expand Down Expand Up @@ -194,7 +194,6 @@ lazy val extras = crossProject(JSPlatform, JVMPlatform)
.jvmSettings(commonJvmSettings: _*)
.jsSettings(commonJsSettings: _*)
.dependsOn(macros, platform, util, core, data)

lazy val docs = project
.in(file("docs"))
.enablePlugins(MicrositesPlugin)
Expand All @@ -207,7 +206,12 @@ lazy val docs = project
.settings(noPublishSettings)
.enablePlugins(MdocPlugin)
.settings(
mdocIn := (Compile / sourceDirectory).value / "mdoc"
mdocIn := (Compile / sourceDirectory).value / "mdoc",
mdocVariables := Map(
"VERSION" -> version.value
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 this is great!

),
// NOTE: disable link hygine to supress dead link warnings because mdoc does not go well with Jekyll
mdocExtraArguments ++= Seq("--no-link-hygiene")
)
.settings(commonJvmSettings: _*)

Expand Down Expand Up @@ -316,7 +320,7 @@ lazy val docSettings = Seq(
micrositeHighlightTheme := "atom-one-light",
micrositeHomepage := "https://typelevel.org/spire",
micrositeBaseUrl := "spire",
micrositeDocumentationUrl := "/spire/api/spire/index.html",
micrositeDocumentationUrl := "https://www.javadoc.io/doc/org.typelevel/spire_2.13/latest/spire/index.html",
micrositeDocumentationLabelDescription := "API Documentation",
micrositeExtraMdFiles := Map(
file("AUTHORS.md") -> ExtraMdFileConfig(
Expand Down Expand Up @@ -347,6 +351,7 @@ lazy val docSettings = Seq(
),
micrositeGithubOwner := "typelevel",
micrositeGithubRepo := "spire",
micrositeTheme := "pattern",
micrositePalette := Map(
"brand-primary" -> "#5B5988",
"brand-secondary" -> "#292E53",
Expand Down
16 changes: 8 additions & 8 deletions docs/src/main/mdoc/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ section: "Home"
position: 0
---

[![Build Status](https://api.travis-ci.org/typelevel/spire.png)](https://travis-ci.org/non/spire/)
[![Continuous Integration](https://github.com/typelevel/spire/actions/workflows/ci.yml/badge.svg)](https://github.com/typelevel/spire/actions/workflows/ci.yml)
[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/typelevel/spire?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![codecov.io](https://codecov.io/github/typelevel/spire/coverage.svg?branch=main)](http://codecov.io/github/typelevel/spire?branch=main)
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.typelevel/spire_2.11/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.typelevel/spire_2.11)
Expand Down Expand Up @@ -39,8 +39,8 @@ The [Spire mailing list](http://groups.google.com/group/typelevel/)
is shared with other [Typelevel projects](http://typelevel.org).
It is the place to go for announcements and discussions around Spire.
When posting, place the word `[spire]` at the beginning of your subject.
We also have a guide on [contributing to Spire](CONTRIBUTING.md) as well
as a guide that provides information on [Spire's design](GUIDE.md).
We also have a guide on [contributing to Spire](./extra_md/contributing.html) as well
as a guide that provides information on [Spire's design](./guide.html).

Spire has maintainers who are responsible for signing-off on and
merging pull requests, and for helping to guide the direction of Spire:
Expand All @@ -65,7 +65,7 @@ JVM and JS platforms.
To get started with SBT, simply add the following to your `build.sbt` file:

```
libraryDependencies += "org.typelevel" %% "spire" % "0.17.0"
libraryDependencies += "org.typelevel" %% "spire" % "@VERSION@"
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice

```

(Previous to 0.14.0, Spire was published under *org.spire-math*
Expand Down Expand Up @@ -129,7 +129,7 @@ introduces several new ones, all of which can be found in `spire.math`:
* `Trilean` value class supporting three-valued logic
* `FixedPoint` fractions with `Long` numerator and implicit denominator (in *extras*)

Detailed treatment of these types can be found in the [guide](GUIDE.md).
Detailed treatment of these types can be found in the [guide](./guide.html).

### Type Classes

Expand Down Expand Up @@ -179,7 +179,7 @@ implicits which provide unary and infix operators for the type classes. The
easiest way to use these is via a wildcard import of `spire.implicits._`.

Detailed treatment of these type classes can be found in the
[guide](GUIDE.md).
[guide](./guide.md).

### Getting Started

Expand Down Expand Up @@ -565,6 +565,6 @@ criticisms, and/or praise are welcome, especially from numerical analysts! ;)

Copyright 2011-2017 Erik Osheim, Tom Switzer

A full list of contributors can be found in [AUTHORS.md](AUTHORS.md).
A full list of contributors can be found in [AUTHORS.md](./extra_md/authors.html).

The MIT software license is attached in the [COPYING](COPYING) file.
The MIT software license is attached in the [COPYING](./extra_md/copying) file.