BrowseDoc: Support .browse files #92
Conversation
| @@ -23,6 +23,7 @@ rule toPrecision { | |||
|
|
|||
| # Math.* fns | |||
| rule abs { bind x; return (native:fn abs $x) } | |||
| #* @help { The arc-cos of a number } | |||
There was a problem hiding this comment.
should we use ## instead of #*?
There was a problem hiding this comment.
I have no strong preference either way
There was a problem hiding this comment.
That definitely looks better but I chose this because I was thinking of how people like to do
###################
# Section title #
###################
Which would trigger the ## check
There was a problem hiding this comment.
While that's true, it's fine because we have a second layer of @help... (i.e. they need to use @ for a tag)
Even in JS, people do this all the time:
/*********************\
*** Section Title ***
\*********************/
| set HOUR $MINUTE * 60 | ||
| set DAY $HOUR * 24 | ||
| set WEEK $DAY * 7 | ||
| #*Number of seconds in a minute |
There was a problem hiding this comment.
Space after #* please 🙏
Also, I'd love it if you (in a new PR) can add this to the @browselang/format package so we can start formatting BrowseDoc :)
There was a problem hiding this comment.
Create an issue and self-assign if you're doing something else and don't want to do this right now. The formatter is fun to work with though :)
| @@ -65,7 +66,9 @@ const main = async () => { | |||
|
|
|||
| const outputs = await Promise.all( | |||
| pages.map(([stem, doc]) => | |||
| markdownPlugin(doc, path.join(outPath, stem + ".md")) | |||
| Object.keys(doc).map((scope) => | |||
There was a problem hiding this comment.
I did this earlier so the output can include docs for multiple scopes into a single file.
This is important sometimes. For example:
-
the
rulescope (which hasbindandreturndoesn't need it's own unique doc page, but lives inside thestddoc): https://github.com/windsorio/browse/wiki/API-Reference. The docs there even use@linkbetween the scopes since they are tightly coupled, so it's imperative that they are in the same file -
the
pageandbrowserscopes should be in a single file, maybe calledwebsince they are coupled. Or, they could be in their own files, but should probably atleast be in their own folder since they are tightly coupled
I think what I did was "better" - it's still opinionated since we assume files are the final output, but really we're copy-pasting things to github wiki, and ideally we can abstract this out like JSDoc/JavaDocs etc. does so it simply spits out an IR, and then there's a different plugin that produces HTML/Markdown/.txt files etc.
I think you're going a step back from that by limiting things to one scope per file
There was a problem hiding this comment.
IIRC I did this because I wanted the default behavior to be that the filename was the scope name in the case that the user doesn't provide an @name argument. Using this method the default name for Math was 'main' because it's in the main file. I'll fix it so that both functionalities stay intact.
* origin/pre: format everything gitignore out in docs update publishing script and publish new stable version Bugs: `match` scoping, `page` parsing and optional (?) rule formatting (#95) Update thegazette.browse example to use pageConfig Undo headless change in twitch.browse example Add support for browserConfig and update examples prerelease version update snytax highlighter add example add throw and match rules remove ? web scraping functions add ? syntax for optional error handling for rules Format code with prettier (#91) Add .deepsource.toml
|
This pull request is being automatically deployed with Vercel (learn more). 🔍 Inspect: https://vercel.com/windsor/browse/ibd7fbqiu |
No description provided.