docs: Rework consistency and style

[dybucc]

There are some scattered comments around the documentation comments that seem to replicate to a smaller degree the actual documentation comments. I'm not sure whether I should remove them as well.

[dybucc]

The tests CI seems to be failing because of the reason reported on #985. I believe merging that PR should solve the issue with tytanic, but likely still fail the tree test, as commented on #985.

[dybucc]

TL;DR still a WIP, and I have a few questions.

I added a few things to the documentation that seemed like they were missing. There's a few things I'm not sure about and so I've not touched, like the Projections subsection from the Draw Shapes section, seeing how it's got no description. I also wonder if rect-around should be within the rect page, judging from other such functions like circle and circle-through.

I'm also not quite sure about why some function parameters have defaults set in their documentation comments, while others simply trust tidy will rightly set the default arguments. Also, in n-star's documentation, the stroke styling option uses different types and refers to other types with an ellipsis; is this intentional? From reading the implementation, it seems to be used with an internal API that does directly document stroke as the parameter type. I'm also confused by the alternating use of {{type}} to indicate links to specific types, and the use of <Type> tags.

Also, are there any plans to use a Typst-specific autoformatter? I understand typstyle seems to be in wide use but doesn't yet support configuration files on its latest stable release as of writing this, so maybe it'd be alright to integrate it into CI for PRs and into some pre-commit hook for maintainers with write access?

[dybucc]

I've been working on a few other changes.
These are mostly about keeping consistency across docstrings, and include:

• Limitting docstrings to 80 columns, except for function parameters, which the
  current parser doesn't seem to recognize as a single one if it detects a
  newline. I have also broken this rule for Markdown lists to keep some
  consistency with the parameter formatting, even if Markdown lists do get
  correctly parsed.
• I'm not sure whether the site's parser also creates links to other
  documentation items the way tidy does, by using the @@target-symbol
  syntax, and I don't know JS to change it.
• Since the version in use of tidy is older than Typst 0.13, the tiling type
  doesn't get an automatic link to the official Typst documentation, as before
  Typst 0.13 it was called pattern. A temporary solution I thought of was to
  add tiling as a custom type to custom-types.js, and have it link to the
  official Typst documentation, as I don't know if you want to update tidy
  considering the manual.pdf revamp doesn't seem to be using it anymore [Resurect manual pdf #974].

I also have some more doubts, added to the ones in the previous comment:

• I also don't quite know why the merge-path function seems to say that hidden
  elements will be ignored, but still offers a parameter to opt-in or out of
  considering such elements.

[johannes-wolf]

• I also don't quite know why the merge-path function seems to say that hidden
  elements will be ignored, but still offers a parameter to opt-in or out of
  considering such elements.

I guess I forgot to update the comment.

[johannes-wolf]

• Limitting docstrings to 80 columns, except for function parameters, which the
  current parser doesn't seem to recognize as a single one if it detects a
  newline. I have also broken this rule for Markdown lists to keep some
  consistency with the parameter formatting, even if Markdown lists do get
  correctly parsed.

Nice! They are that long, because I think the current (non-Resurect manual.pdf) branch is unable to correctly parse parameter documentation split over multiple lines.

[dybucc]

• I also don't quite know why the merge-path function seems to say that hidden
  elements will be ignored, but still offers a parameter to opt-in or out of
  considering such elements.

I guess I forgot to update the comment.

Done.

[dybucc]

• Limitting docstrings to 80 columns, except for function parameters, which the
  current parser doesn't seem to recognize as a single one if it detects a
  newline. I have also broken this rule for Markdown lists to keep some
  consistency with the parameter formatting, even if Markdown lists do get
  correctly parsed.

Nice! They are that long, because I think the current (non-Resurect manual.pdf) branch is unable to correctly parse parameter documentation split over multiple lines.

I'm assumming you mean the generate-api.js file under the scripts/ directory in the docs repo.

[johannes-wolf]

Note that with the resurrection of the PDF manual, I also want to convert all the web-pages (custom-types.mdx, ...) to Typst. Changing docstrings to non-typst format will lead to a lot of merge conflicts.

[dybucc]

Note that with the resurrection of the PDF manual, I also want to convert all the web-pages (custom-types.mdx, ...) to Typst. Changing docstrings to non-typst format will lead to a lot of merge conflicts.

Just committed all the prior changes updated to use only Typst syntax. I have removed changes to custom-types.mdx, but I have kept type links in docstrings with the {{type}} syntax. Should I replace this syntax with something else when referring to referenceable types in docstrings?

[johannes-wolf]

Just committed all the prior changes updated to use only Typst syntax. I have removed changes to custom-types.mdx, but I have kept type links in docstrings with the {{type}} syntax. Should I replace this syntax with something else when referring to referenceable types in docstrings?

The problem is, that Typst' native links @name won't work with the Typst→MDX export, so we need a solution for that (tbh. I just removed some links to work around that :/).

[dybucc]

Just committed all the prior changes updated to use only Typst syntax. I have removed changes to custom-types.mdx, but I have kept type links in docstrings with the {{type}} syntax. Should I replace this syntax with something else when referring to referenceable types in docstrings?

The problem is, that Typst' native links @name won't work with the Typst→MDX export, so we need a solution for that (tbh. I just removed some links to work around that :/).

I'll just leave the {{type}} syntax for now, and see if I can do something with the parser.

[dybucc]

I've been working on the parser. I've so far managed to more efficiently handle function signature parsing, but I've still got to further refine the output to get something similar/better than the current parse-function-signature. This work will be part of another PR once I get this refactor done (but before I refactor the rest of the parser to e.g. support multiline function parameter docstrings.)

I also noticed there were some non-documentation comments getting picked up in the parsing process due to them having (possibly) wrong Typst line comments (i.e. starting with /// instead of //.) I noticed this in the bezier.typ file where a function declared within another function was getting documented, when it shouldn't have, as it's not reachable by library users. I don't know how prevalent this is across the codebase, so I've also changed some of that on the docstring extractor (more on this once I open the actual PR with the parser changes.)

In terms of type syntax not getting correctly picked up by the Typst -> MDX export, that's still something I've not looked into, seeing how there's still work to be done on the manual (before getting it to the web.)

EDIT: the PR I'm referring to above is #996, and the function signature parsing work is done; next steps are parameter parsing optimizations and multiline parameter docstring parser support.