Support var linking across namespaces + wikilinks syntax #20
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This commit introduces a significant change in how var linking is
performed:
- MD sections are anchored with stringified qualified symbols
- Munging down while generating TOC is gone
- A map of `namespace` -> `#{vars}` is prepared
- During var linking, that map is used to detect if a value should be
linked to a namespace or a var
The core `quickdoc` function was indeed applying defaults using the `:or` construct in destructuring. However, raw options were then passed to inner functions, resulting in defaults not being enforced downstream.
Introduces a new option `:var-pattern` deciding how vars are detected in docstrings. Set to `:backticks` by default. Users can also choose `:wikilinks` (aka double brackets) so that is behave like Codox and Cljdoc.
Owner
|
Tried this out on fs here: https://github.com/babashka/fs/blob/fs-quickdoc/API.md#babashka.fs/real-path Looks good I think! We should really be starting to think about tests though :-) |
Contributor
Author
|
I thought it would be a good idea eventually doing it in 2 phases: synthesize Clj-kondo analysis into a hiccup-like structure resembling the MD output and then pass it through a formatter whose job is printing the file. That way testing the synthesis phase will be easy and formatting can be pluggable. For instance, another incoming PR will be about little cosmetic changes and might be more a matter of taste. |
Owner
|
Yeah, that sounds good: analysis -> data -> md |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The first commit describes how var linking has been generalized and made more reliable by eschewing
memoand using analysis data. Eventually, the last commit provides support for[[var]]as discussed on Clojurians.Seems to behave well with my docs although I use that wikilinks syntax. I quickly tried with a few backticks and it seems to work as well but please give it a try first :)