Skip to content

Repair the docs build, and bring the quickstart to 2.0.0 - #32

Merged
Rafael-SOWNet merged 2 commits into
masterfrom
docs/2.0.0
Aug 11, 2026
Merged

Repair the docs build, and bring the quickstart to 2.0.0#32
Rafael-SOWNet merged 2 commits into
masterfrom
docs/2.0.0

Conversation

@Rafael-SOWNet

Copy link
Copy Markdown
Contributor

Merge this after v2.0.0 is published on NuGet — the quickstart tells the reader to
install a version that has to exist first. Everything else here is a repair and is
independent of that.

The docs build has been broken since 2026-01-03

asc-community/AngouriMath@f0db3eef moved the library up a folder, and two places here still
pointed at the old layout:

was is
amsite.fsx publish src/AngouriMath/Sources/AngouriMath/AngouriMath .../Sources/AngouriMath
NaiveStaticGenerator reading AngouriMath.xml the same stale path the same fix

The first made dotnet fsi amsite.fsx init fail outright, so nothing downstream ran. The
second would have produced an empty almanac even if the publish had succeeded. They have to
move together and each now says so in a comment.

Two further things stopped it independently, so fixing only the paths would not have been
enough:

  • NaiveStaticGenerator targeted net6.0, out of support since November 2024 and not
    present on a current machine — dotnet fsi amsite.fsx build fails with
    "To install missing framework… 6.0.0". Now net10.0. Yadg.NET stays on net6.0 and is
    referenced as a library, which is fine.
  • The workflows used actions/checkout@v2 and actions/setup-dotnet@v1, which GitHub no
    longer runs. Now @v4, one setup-dotnet at 10.x instead of separate .NET 6 and .NET 7
    steps, and github-pages-deploy-action@v4 instead of a pinned 4.1.4. The nine ls lines
    that debugged the old paths are gone, and the deployment job declares
    permissions: contents: write for the gh-pages push.

Verified end to end on this commit: init then build produces 1944 pages. The almanac
is among them and reflects 2.0 — docs/AngouriMath/Entity/Latexize.html is there, Ceil,
Floor, Round, Min, Max and Gcd are there, and the members 2.0 removed are not.

Quickstart

  • --prerelease is gone. It was installing 2.0.0-preview.2 against pages describing
    something else.
  • The MyGet nightly instructions are gone. The feed URL answers but lists no AngouriMath
    package, and it was retired in asc-community/AngouriMath#701. Same for the #i form in
    the notebook section.
  • The F# and notebook hello-world programs did not compile. They opened Core and
    Functions by paths that do not resolve, and called parse and differentiate, which are
    parsed and derivative. This was the first program a new F# reader runs.
  • The C++ snippet had a stray ; after its #include and no <iostream>.
  • Added which frameworks the package targets, because a net7.0 project now resolves the
    netstandard2.0 asset and loses the generic-math surface with it, and a pointer to
    BREAKING-CHANGES.md for anyone coming from 1.x.

The C# and F# hello-world blocks now carry <!-- amcheck:cs --> / <!-- amcheck:fs -->, so a
harness compiles and runs them against a build of the library. Both pass. The annotation is
an HTML comment and does not render. 28 other pre code blocks on the site are shell, CMake
or notebook lines and are not annotated; that count is reported rather than passed over.

What's new

PackageReleaseNotes in every published package sends the reader to /whatsnew, whose
newest entry was 1.4-preview.4, marked "in development". Added the 2.0.0 entry: the
renames and removals, the answers that changed because the old ones were wrong, what is new,
and a link to BREAKING-CHANGES.md at the top, since several entries are a wrong answer
becoming a right one and that still breaks code built on the wrong one. 1.4-preview.4 loses
its "[in development]".

Also

README.md said to install .NET 6 to run the site locally; it is .NET 10 now.

Related: asc-community/AngouriMath#883 is the release itself, and the wiki has been
corrected and is now machine-checked against a 2.0.0 build (86 samples, 0 compile errors, 0
output mismatches).

The generation had been broken since asc-community/AngouriMath@f0db3eef moved the
library up a folder on 2026-01-03. Two places still pointed at the old layout:
amsite.fsx published from Sources/AngouriMath/AngouriMath, which no longer exists,
so `init` failed outright; and NaiveStaticGenerator read AngouriMath.xml from the
same stale path, so the almanac would have been empty even if the publish had
succeeded. They have to move together, and each now says so.

Two more things stopped it independently of that. The generator targeted net6.0,
out of support since November 2024 and no longer present on a current machine. And
the workflows used actions/checkout@v2 and actions/setup-dotnet@v1, which GitHub no
longer runs -- so the deployment could not have succeeded whatever the paths said.

Verified end to end on this commit: `init` then `build` produces 1944 pages, the
almanac among them, with Latexize present and the members 2.0 removed absent.

The quickstart:

- Drops --prerelease. 2.0.0 is a release, and the flag was installing a preview
  against pages that describe something else.
- Removes the MyGet instructions. That feed answers but lists no AngouriMath
  package, and it was retired in asc-community/AngouriMath#701.
- Fixes the F# and notebook hello-world programs, which did not compile: they
  opened Core and Functions by paths that do not resolve and called `parse` and
  `differentiate`, which are `parsed` and `derivative`. This was the first program
  a new F# reader runs.
- Fixes the C++ snippet, which had a stray semicolon after its #include and no
  <iostream>.
- Says which frameworks the package targets, since a net7.0 project now silently
  resolves netstandard2.0 and loses generic math with it.

The C# and F# hello-world blocks carry an amcheck annotation, so a harness compiles
and runs them against a build of the library rather than leaving them to a reader
to discover.

What's new gets its 2.0.0 entry. PackageReleaseNotes sends every NuGet reader to
that page, and its newest entry was 1.4-preview.4 marked "in development".
uninit deletes the AngouriMath, Yadg.NET and wiki clones, and git marks the files
under .git/objects/pack read-only. Directory.Delete refuses a read-only file on
Windows, so uninit failed there with UnauthorizedAccessException on a pack .idx --
the only red leg of the matrix, with init, build and clean all passing.
@Rafael-SOWNet
Rafael-SOWNet merged commit 72574e3 into master Aug 11, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant