search

RunestoneInteractive / rs

A New Monorepo structure for Runestone
Other
40 stars 66 forks source link

strawman attempt to not require author configuration of `published` dir #494

Closed StevenClontz closed 3 months ago

StevenClontz commented 3 months ago

Note that some of the checks I've retained here are redundant with the validation already done on PreTeXt-CLI's side. Maybe @oscarlevin or @bjones1 can point out which ifs can be safely removed as the Project won't validate if they aren't satisfied anyway?

StevenClontz commented 3 months ago

I think it's also possible to remove the necessity of having authors set the document-id altogether, since I think we can pass it along as a stringparam. This would mean that, if we wanted, Runestone could be improved to not require a specific runestone target at all: given an arbitrary PreTeXt project, we can construct a Runestone target with all the configuration needed on Runestone's side.

bnmnetp commented 3 months ago

To properly be in the runestone library we also ask authors to set additional information in docinfo, like a blurb.

Then there is the question of the publisher file which needs to have <platform host="runestone"> Not sure how we let pretext know about that.

If we solve that, then I guess we could get someone up and running on Runestone without any additional configuration. by assuming that the document-id is the same as the name of the parent directory of where we find the project.ptx file.

StevenClontz commented 3 months ago

See https://github.com/PreTeXtBook/pretext-cli/blob/e902b5b5ef923c5d498db0657e4c3e1a7abb4cdd/pretext/project/__init__.py#L585 for <platform host="runestone"> - update to PR incoming

StevenClontz commented 3 months ago

As for blurb/shelf, we already deliver this in our book template:

https://github.com/PreTeXtBook/pretext-cli/blob/e902b5b5ef923c5d498db0657e4c3e1a7abb4cdd/templates/book/source/docinfo.ptx#L10

StevenClontz commented 3 months ago

This PR to PreTeXt-CLI will encourage the use of blurb in earlier stages of authoring, by using it to generate the website for a project with multiple deploy targets: https://github.com/PreTeXtBook/pretext-cli/pull/771

bnmnetp commented 3 months ago

Having just coached a few authors through updating their project.ptx file and publication file to get a runestone build working, I feel like either this PR needs to be merged, or we need to revisit including a template for runestone from the start. Even having some comments in the project.ptx file about what the defaults are, and where to look in the docs for help would go a long way. Especially for the contingent of CS folks who just dive right in to editing files.

Increasingly, authors want to see what a runestone build looks like. Telling them that it looks just like the web build except for X, Y, and Z is an insufficient answer. But giving them a turnkey solution for getting started in a codespace and then asking them to make the leap to editing configuration files to get a different target is asking a lot.

Even after pointing them to https://pretextbook.org/doc/guide/html/sec-publishing-to-runestone-academy.html it seems hard to get right. Additionally, somewhere there is a gremlin that is incorrectly adding an @platform to the <html> tag. which results in crazy Pydantic validation errors.

I think we need to keep the ability to create a runestone target in the publication file, and we need to honor that when it is there. There will certainly be plenty of cases where we want to customize a publisher file for runestone.

I'm going to put this PR on a branch and see what happens.

bnmnetp commented 3 months ago

OK, so I'm working through this, as written: but maybe not as I had assumed from the conversation. I'm more or less documenting my thoughts as I hack away at the PR.

  1. We still have to have a runestone target or we'll exit

  2. We have to specify the source path and the publication file

  3. If there is no runestone target then adopt the "web" target rather than exiting.

  4. if there is no document-id then emit a warning but use the name of the course

bnmnetp commented 3 months ago

Success!

If there is no runestone target I can get a complete build adopting either web or html If there is no document-id then I use the name of the course as passed to the function. I do validate the path. If there is a runestone target then the usual validation still happens.

I think this is good.