Adapt docgen to use the mkdocs material theme #4226

mfelsche · 2022-11-03T18:32:56Z

As the ponylang-mkdocs-theme wasn't maintainable anymore. This puts all the necessary tweaks inside the generated files (logo, custom css, theme adaptions and extensions) and only depends on the user to have mkdocs and the python package material-mkdocs installed to generate and serve html docs.

ponylang-main · 2022-11-03T18:33:17Z

Hi @mfelsche,

The changelog - changed label was added to this pull request; all PRs with a changelog label need to have release notes included as part of the PR. If you haven't added release notes already, please do.

Release notes are added by creating a uniquely named file in the .release-notes directory. We suggest you call the file 4226.md to match the number of this pull request.

The basic format of the release notes (using markdown) should be:

## Title

End user description of changes, why it's important,
problems it solves etc.

If a breaking change, make sure to include 1 or more
examples what code would look like prior to this change
and how to update it to work after this change.

Thanks.

mfelsche · 2022-11-04T14:24:27Z

Windows build is failing.

It seems we either compile stuff on windows as C++ or not with C99 standard. Investigating... Any help appreciated.

SeanTAllen · 2022-11-04T17:45:49Z

This also contains an improvement to sort items in a package alphabetically to make it easier to find classes/actors/primitives.

I'm not sure that is an improvement. Can you revert that change and we can discuss it as a separate change?

SeanTAllen · 2022-11-04T17:47:57Z

@mfelsche I dont see the Window build as having failed. I see an arm build failing. Can you clarify?

chalcolith · 2022-11-04T17:48:11Z

I am in favour of alphabetizing. Hunting for things in the docs is a perennial source of friction for me.

SeanTAllen · 2022-11-04T17:50:10Z

I assume that people put thought into the order of their methods and randomly moving them around based on name is "not a particularly good thing" when listing in docs. As I said, I'd like to revert the change as it isn't specifically part of this change and it can be discussed further elsewhere.

mfelsche · 2022-11-04T18:47:43Z

Fair point about the ordering being unrelated here. Will put it into another PR. One additional point: Only the order of classes/primitives/actors is affected, not the order of methods/behaviours. Ordering the former alphabetically makes it easier to find them in my experience. E.g. trying to find the docs for Array in builtin is an annoying exercise. But enough of that.

The forelast commit was failing on windows as we seem to compile our c sources as C++ somehow. Gotta investigate the arm build error.

SeanTAllen · 2022-11-04T19:06:53Z

I think the arm build error was the instance being rescheduled and then it looks like it didnt restart? I've restarted it as that is what it looks like happened to me.

Normally, when an instance is rescheduled, it gets restarted, I have however seen it not restart from time to time.

SeanTAllen · 2022-11-04T19:35:14Z

@mfelsche i ran it and it passed.

mfelsche · 2022-11-04T19:50:02Z

I did remove the sorting change.

SeanTAllen · 2022-11-04T20:00:40Z

So if this requires a specific theme, should we be updating the help output for --docs? I'm thinking no, but as you mentioned, having a section in the tutorial would be good.

mfelsche · 2022-11-04T20:02:40Z

I will add a section about generating documentation to the tutorial. 👍

SeanTAllen · 2022-11-05T19:06:18Z

Before we merge this, I'd like to add some(thing) around making sure that docgen is working as part of either nightlies or PRs were we verify that the docs build. It would probably be just a nightly job that verifies everything builds but doesn't update anything. I'll get to that soon-ish. At the moment, I'm sick and feverish so it will be at least a bit.

@mfelsche are you ok with the delay?

mfelsche · 2022-11-05T20:33:17Z

Of course I am! Take all the time you need and most importantly get well soon!
You can also point me at the place where such a job would be implemented in your mind, and i do the typing.

SeanTAllen · 2022-11-05T20:39:09Z

@mfelsche the .ci-dockerfiles/stdlib-builder should be updated as part of this PR, yes?

SeanTAllen · 2022-11-05T20:40:38Z

The https://github.com/ponylang/library-documentation-action should also be updated.

mfelsche · 2022-11-05T20:49:12Z

@mfelsche the .ci-dockerfiles/stdlib-builder should be updated as part of this PR, yes?

It is, i updated it to install the necessary mkdocs-metarial theme.

The https://github.com/ponylang/library-documentation-action should also be updated.

Will do so.

SeanTAllen · 2022-11-05T21:56:30Z

Here's a PR to add a nightly documentation build...

#4229

SeanTAllen · 2022-11-06T17:08:31Z

Two small changes please @mfelsche

The release notes, please have no newlines in paragraphs. Then it will look good in whatever medium it is displayed (like on github and elsewhere).

Two, this is a breaking change so can you add to the release notes to note the change that users will have to do (installing material theme, not installing the old mkdocs-ponylang) in order to have everything continue to work.

Once those updates are made, I'll merge this.

SeanTAllen · 2022-11-07T20:18:10Z

I see you fixed the Windows issue in the PR. Given this PR fixes two different things please do the following.

Add release notes for each fix directory to "next-release.md" and remove the interim release notes file.
Add changelog entries for each change (mkdocs material and windows fix) directly to the CHANGELOG in the appropriate places with the appropriate formatting with both linking to this PR.

Or,

please remove the Windows fixes from this PR and open another for it.

Your choice. Let me know which you decide you want to do.

As the ponylang-mkdocs-theme wasn't maintainable anymore. This puts all the necessary tweaks inside the generated files (logo, custom css, theme adaptions and extensions) and only depends on the user to have mkdocs and the python package material-mkdocs installed to generate and serve html docs. This also contains an improvement to sort items in a package alphabetically to make it easier to find classes/actors/primitives.

Signed-off-by: Matthias Wahl <matthiaswahl@m7w3.de>

mfelsche · 2022-11-07T20:47:14Z

I chose the path of pain (1).

SeanTAllen · 2022-11-07T20:49:18Z

CHANGELOG.md

@@ -8,13 +8,14 @@ All notable changes to the Pony compiler and standard library will be documented

 - Avoid fairly easy to trigger overflow in Windows Time.nanos code ([PR #4227](https://github.com/ponylang/ponyc/pull/4227))
 - Fix incorrect interaction between String/Array reserve and Pointer realloc ([PR #4223](https://github.com/ponylang/ponyc/pull/4223))
+- Fix broken docgen on Windows ([PR #4226](https://github.com/ponylang/ponyc/pull/4223))


For some reason, I can't suggest a change anymore. No idea why. The URL points to the wrong PR.

Instead of docgen, can we say "documentation generation"

SeanTAllen · 2022-11-07T20:50:17Z

.release-notes/next-release.md

+
+This is a **Breaking Change** in so far that users that want to generate documentation with ponyc now have to install the python package `mkdocs-material` instead of `mkdocs-ponylang` to generate their documentation in HTML form with mkdocs. The [library documentation github action](https://github.com/ponylang/library-documentation-action) will have the correct dependencies installed, so no changes should be needed when using it.
+
+## Fix broken docgen on Windows


Can we call it documentation generation for this release note?

SeanTAllen · 2022-11-07T20:50:29Z

.release-notes/next-release.md

@@ -16,3 +16,12 @@ This could lead to very surprising results if `reserve` had been called by `unde

 In order to make documentation on a class, actor, primitive or struct easier to find, they are now sorted alphabetically inside their package.

+## Adapt docgen to only depend the mkdocs material theme
+
+We used to have our own mkdocs theme for ponylang documentation, it was based off of the mkdocs-material theme. This change puts the adaptationswe need into the mkdocs.yml file itself, so we don't depend on our own theme anymore, but only on the upstream mkdocs-material.


"adapationwe" is a typo.

SeanTAllen · 2022-11-07T20:50:59Z

.release-notes/next-release.md

@@ -16,3 +16,12 @@ This could lead to very surprising results if `reserve` had been called by `unde

 In order to make documentation on a class, actor, primitive or struct easier to find, they are now sorted alphabetically inside their package.

+## Adapt docgen to only depend the mkdocs material theme


Can we call it "documentation generation" rather than docgen?

SeanTAllen · 2022-11-07T20:51:18Z

CHANGELOG.md

 ### Changed

 - Sort package types in documentation ([PR #4228](https://github.com/ponylang/ponyc/pull/4228))
+- Adapt docgen to use the mkdocs material theme ([PR #4226](https://github.com/ponylang/ponyc/pull/4226)


Can we call it documentation generation rather than "docgen"?

Still have this one to update.

SeanTAllen · 2022-11-07T20:54:19Z

.release-notes/next-release.md

+
+## Fix broken documentation generation on Windows
+
+Generating documentation has been broken on windows: `ponyc` was not able to write the documentation files, due to path handling issues on windows. This is now fixed and documentation generation is working again on windows.


Small one I see. windows should be Windows in a few places in here.

SeanTAllen · 2022-11-07T20:54:47Z

CHANGELOG.md

@@ -8,13 +8,14 @@ All notable changes to the Pony compiler and standard library will be documented

 - Avoid fairly easy to trigger overflow in Windows Time.nanos code ([PR #4227](https://github.com/ponylang/ponyc/pull/4227))
 - Fix incorrect interaction between String/Array reserve and Pointer realloc ([PR #4223](https://github.com/ponylang/ponyc/pull/4223))
+- Fix broken docgen on Windows ([PR #4226](https://github.com/ponylang/ponyc/pull/4226))


Can we call it documentation generation here as well?

SeanTAllen · 2022-11-08T00:42:28Z

I merged this. If it passes the "works as expected test" tomorrow night when it goes into a nightly then I will note that the library documentation action PR should be merged on the next release.

@mfelsche is there a tutorial change open yet?

mfelsche added changelog - changed Automatically add "Changed" CHANGELOG entry on merge documentation Improvements or additions to documentation discuss during sync Should be discussed during an upcoming sync labels Nov 3, 2022

mfelsche mentioned this pull request Nov 5, 2022

Change Dockerfile to install the required material theme ponylang/library-documentation-action#26

Merged

mfelsche force-pushed the docgen-theme-embed branch from ebfb0c2 to c2e2d29 Compare November 7, 2022 09:20

mfelsche added 5 commits November 7, 2022 21:36

Update the stdlib documentation builder Dockerfile

fe83e17

Signed-off-by: Matthias Wahl <matthiaswahl@m7w3.de>

Add release notes

d002d72

Try to make it work on windows

f229ad6

Do not sort elements in docs

5d4b6d4

Matthias Wahl and others added 3 commits November 7, 2022 21:37

Make docgen work on windows

3e8d5ee

Update release notes

e5e8b97

Manual release notes and changelog fiddlin

eadf381

mfelsche force-pushed the docgen-theme-embed branch from c2e2d29 to eadf381 Compare November 7, 2022 20:45

SeanTAllen reviewed Nov 7, 2022

View reviewed changes

Fixing the CHANGELOG on the path of pain

91b5764

SeanTAllen reviewed Nov 7, 2022

View reviewed changes

SeanTAllen removed the changelog - changed Automatically add "Changed" CHANGELOG entry on merge label Nov 7, 2022

release notes wording

e131cf9

SeanTAllen reviewed Nov 7, 2022

View reviewed changes

mfelsche added 2 commits November 7, 2022 21:56

Even more wordings and capitalizing words

5ea761f

Leftovers

3d63e9e

SeanTAllen merged commit a52451b into main Nov 8, 2022

SeanTAllen deleted the docgen-theme-embed branch November 8, 2022 00:36

ponylang-main removed the discuss during sync Should be discussed during an upcoming sync label Nov 8, 2022

ponylang-main added the discuss during sync Should be discussed during an upcoming sync label Nov 8, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adapt docgen to use the mkdocs material theme #4226

Adapt docgen to use the mkdocs material theme #4226

mfelsche commented Nov 3, 2022 •

edited

Loading

ponylang-main commented Nov 3, 2022

mfelsche commented Nov 4, 2022

SeanTAllen commented Nov 4, 2022 •

edited

Loading

SeanTAllen commented Nov 4, 2022

chalcolith commented Nov 4, 2022

SeanTAllen commented Nov 4, 2022

mfelsche commented Nov 4, 2022

SeanTAllen commented Nov 4, 2022 •

edited

Loading

SeanTAllen commented Nov 4, 2022

mfelsche commented Nov 4, 2022

SeanTAllen commented Nov 4, 2022

mfelsche commented Nov 4, 2022

SeanTAllen commented Nov 5, 2022

mfelsche commented Nov 5, 2022

SeanTAllen commented Nov 5, 2022

SeanTAllen commented Nov 5, 2022

mfelsche commented Nov 5, 2022

SeanTAllen commented Nov 5, 2022

SeanTAllen commented Nov 6, 2022

SeanTAllen commented Nov 7, 2022

mfelsche commented Nov 7, 2022

SeanTAllen Nov 7, 2022

SeanTAllen Nov 7, 2022

SeanTAllen Nov 7, 2022

SeanTAllen Nov 7, 2022

SeanTAllen Nov 7, 2022

SeanTAllen Nov 7, 2022

SeanTAllen Nov 7, 2022

SeanTAllen Nov 7, 2022

SeanTAllen Nov 7, 2022

SeanTAllen commented Nov 8, 2022 •

edited

Loading


		This is a Breaking Change in so far that users that want to generate documentation with ponyc now have to install the python package `mkdocs-material` instead of `mkdocs-ponylang` to generate their documentation in HTML form with mkdocs. The [library documentation github action](https://github.com/ponylang/library-documentation-action) will have the correct dependencies installed, so no changes should be needed when using it.

		## Fix broken docgen on Windows

		@@ -16,3 +16,12 @@ This could lead to very surprising results if `reserve` had been called by `unde

		In order to make documentation on a class, actor, primitive or struct easier to find, they are now sorted alphabetically inside their package.

		## Adapt docgen to only depend the mkdocs material theme


		## Fix broken documentation generation on Windows

		Generating documentation has been broken on windows: `ponyc` was not able to write the documentation files, due to path handling issues on windows. This is now fixed and documentation generation is working again on windows.

Adapt docgen to use the mkdocs material theme #4226

Adapt docgen to use the mkdocs material theme #4226

Conversation

mfelsche commented Nov 3, 2022 • edited Loading

ponylang-main commented Nov 3, 2022

mfelsche commented Nov 4, 2022

SeanTAllen commented Nov 4, 2022 • edited Loading

SeanTAllen commented Nov 4, 2022

chalcolith commented Nov 4, 2022

SeanTAllen commented Nov 4, 2022

mfelsche commented Nov 4, 2022

SeanTAllen commented Nov 4, 2022 • edited Loading

SeanTAllen commented Nov 4, 2022

mfelsche commented Nov 4, 2022

SeanTAllen commented Nov 4, 2022

mfelsche commented Nov 4, 2022

SeanTAllen commented Nov 5, 2022

mfelsche commented Nov 5, 2022

SeanTAllen commented Nov 5, 2022

SeanTAllen commented Nov 5, 2022

mfelsche commented Nov 5, 2022

SeanTAllen commented Nov 5, 2022

SeanTAllen commented Nov 6, 2022

SeanTAllen commented Nov 7, 2022

mfelsche commented Nov 7, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SeanTAllen commented Nov 8, 2022 • edited Loading

mfelsche commented Nov 3, 2022 •

edited

Loading

SeanTAllen commented Nov 4, 2022 •

edited

Loading

SeanTAllen commented Nov 4, 2022 •

edited

Loading

SeanTAllen commented Nov 8, 2022 •

edited

Loading