usethesource / rascal-tutor Goto Github PK

[ERROR] Failed to execute goal org.rascalmpl:rascal-maven-plugin:0.18.1:tutor (default-cli) on project rascal-tutor: Execution default-cli of goal org.rascalmpl:rascal-maven-plugin:0.18.1:tutor failed: Could not import module lang::rascal::tutor::Compiler: can not find in search path
[ERROR] Advice: |https://www.rascal-mpl.org/docs/Rascal/Errors/CompileTimeErrors/ModuleImport|

This is due to the following:

[INFO] rascal module path addition: |lib://rascal-tutor|

Here because |project://rascal-tutor| is also defined, the current source code in the target folder is superseding the library linked in the rascal-maven-plugin. So we have two bootstrap-levels mixed and since the source files haven't been packaged into the target folder yet, we are also not accidentally running our own code on our own code.

This is currently blocking a release of a newer tutor with better documentation of itself, and better error handling.

The first is the link used to jump to a definition, the second is what the anchor is defined as:

http://localhost:3000/docs/Library/vis/Charts/#vis-Charts-ChartAutoColors
http://localhost:3000/docs/Library/vis/Charts/#vis::Charts-ChartAutoColors

Currently tutor links inside @Synopsis tags are not rewritten to markdown format.

• it fits better here also for maintenance
• the website is better if less-relevant information for general Rascal users is focused into the Packages section

An example is Locations::relativize where the documentation is really different.

for example: http://localhost:3000/docs/Library/util/Validator/

• test functions are mixed with normal functions and that makes the interface looks unnecessarily complex
• test functions would be best with their bodies intact, as they document semantics of the function-under-test
• test functions would be best in a separate section of a module's documentation, such that they can be ignored.

I don't know how to add links to the docusaurus code blocks, or if this could work at all from the client side, but it would be great if we could feed the resolution of names of the type-checker into the documentation generator. That way people could browse in the documented APIs like they can with some Github source code viewers.

• This would take more computation time, so it could be an optional feature for the final publishing stage instead of during a preview.
• Reuse type-checker code from rascal-core which also uses timestamps for incrementalization
• Extracting the right def-use information from .tpl files is already done; this is a basic IDE construction feature we use in VScode and Eclipse
• What happens on the client side with multiple, non-unitary, link targets?

This sounds like a team effort @PaulKlint @JJWTimmer. Maybe we could have a call/meeting sometime in Feb?

I see only empty screenshots when I compile vis/Charts.rsc with the tutor.

[ERROR] Failed to execute goal org.rascalmpl:rascal-maven-plugin:0.12.3:tutor (default-cli) on project website: Execution default-cli of goal org.rascalmpl:rascal-maven-plugin:0.12.3:tutor failed: Stack overflow during pattern compilation near index 2
[ERROR] (?:(?<!\\)|(?<=\\\\))<([a-zA-Z0-9]+)(?:\s*:\s*((?:[^\\<>]|(?:\\[\\<>])|(?:\\)|(?:<[a-zA-Z0-9]+>))*))?>

This is on an input with many literal source locations (and so many \\\). Run mvn compile in rascal-website, branch local-courses to trigger the bug.

http://localhost:3000/docs/Packages/clair/API/lang/cpp/TypeSymbol/

If a function has @memo then make sure the documentation automatically and clearly says what this means for the semantics of the function

This would somehow reuse the maven-plugin, reuse previously generated index.value files (or re-compile the entire project). The goal is to get quicker feedback on embedded code fragments and link usage. auto-complete for links would also be great.

Tutor/Markup/InlineMarkup/Listing/Listing.md:39:0: Ambiguous concept link: module:Content resolves to all of these: //Library/Content.md //Library/Content.md#Content-Content

• Content is a data or an alias in the module Content
• by prefixing the link with module only modules should be linked.
• this is probably a copy/paste issue in the Linker of the tutor compiler.

https://www.rascal-mpl.org/docs/Recipes/BasicProgramming/SourceComments/ shows this:

((rascal-tutor:Tutor)) documentation tags to every declaration

((clair)) does not work, for example. propose to add ((package:clair)) and friends and not just ((clair)) by itself (too many clashes otherwise, consider ((typepal)) and ((flybytes)) where these links already exist as module package folders.

See for example vis::Charts and vis::Graphs

There is a renaming going on to SalixCore that is not done consistently, leading to eventually to this during yarn build in the rascal-website project. This means that the markdown that was generated during the release of salix-core is broken.

Exhaustive list of all broken links found:

- On source page path = /docs/Packages/SalixCore/API/:
   -> linking to ../../../Packages/SalixCore/API/salix/ (resolved as: /docs/Packages/SalixCore/API/salix/)

    at throwError (/Users/jurgenv/Sites/rascal-website/node_modules/@docusaurus/logger/lib/index.js:76:11)
    at handleBrokenLinks (/Users/jurgenv/Sites/rascal-website/node_modules/@docusaurus/core/lib/server/brokenLinks.js:153:47)
    at async buildLocale (/Users/jurgenv/Sites/rascal-website/node_modules/@docusaurus/core/lib/commands/build.js:177:5)
    at async tryToBuildLocale (/Users/jurgenv/Sites/rascal-website/node_modules/@docusaurus/core/lib/commands/build.js:38:20)
    at async mapAsyncSequential (/Users/jurgenv/Sites/rascal-website/node_modules/@docusaurus/utils/lib/jsUtils.js:34:24)
    at async Command.build (/Users/jurgenv/Sites/rascal-website/node_modules/@docusaurus/core/lib/commands/build.js:73:21)

Like definitions of extensions of M3:

This does not end up in the docs:

data M3(int x = 0);

For example on the website the index for course Rascal is merged with the course Library which contains the Rascal syntax module. To be able to link to the course ((course:Rascal)) would help a lot.

See subject.

• either figure out a way to wait until all animations are done,
• or parametrize the millisecond wait time per screenshot

although they can be essential in understanding demo code, and also the API of reusable modules (global configuration is often stored in module variables)

https://www.rascal-mpl.org/docs/Packages/salix-core/API/salix/Index/