Comments (9)
This is a bug. Do you want me to create a PR to fix it? Or do you want to create the PR?
I started writing my own docs generating implementation and encountered some issues with api-extractor module.
Is your implementation open source? Our internal documentation pipeline is unfortunately very complicated (due to requirements of the docs.microsoft.com system), so it would be really useful to have a "reference implementation" that transforms the API Extractor JSON into simple HTML or Markdown pages. If you are coding something like this, it would be awesome if we could include it as part of the the api-extractor package.
I started writing something like this a couple weeks ago, and it revealed a bunch of little bugs and oversights in the JSON file that we had overlooked because our production pipeline has so many steps.
from rushstack.
This is a bug. Do you want me to create a PR to fix it? Or do you want to create the PR?
If you can, it would be better you make the changes. I am not really that familiar with this code our how exactly is done. Here are current changes I made to ApiJsonGenerator.
Is your implementation open source?
Yes, it's in dev
branch. Unfortunately it's a spaghetti code. First version of this package I am making for typescript projects so we don't need to write API docs by hand.
Looked at ApiJsonGenerator
and ApiFileGenerator
files, I was thinking about creating something similar, like ApiMarkdownGenerator
.
from rushstack.
You will have a much easier time if you go JSON --> markdown instead of ApiItem tree --> markdown.
Here is a prototype branch that I was working on, which goes from JSON --> YAML (with each YAML file roughly corresponding to a page on an API documentation web site). The main loop is in ApiYamlWriter.ts. Because JSON is so easy to consume, the whole thing is only a couple hundred lines of code.
If you have a general spec for what you want your files to look like, this prototype would be pretty easy to repurpose to produce Markdown instead of YAML, particularly if we could use a proper library (markdown-creator?) instead of string manipulations to create the output. (Markdown has a very complex grammar, so we found that it's difficult to emit strings that don't accidentally get interpreted as formatting styles. Is that asterisk an asterisk, or is it part of a boldfaced region? Ooops, why did those spaces get interpreted as a callout block?)
My aim here would be to maintain a concise code sample that people can hack up and customize for their own documentation needs. (This is probably easier than providing a fancy templating system, which will never be customizable enough.) It would also give me a cheap way to validate new documentation scenarios, without waiting for our own big pipeline to support them.
Lemme know if you'd want to collaborate on something like that.
from rushstack.
You will have a much easier time if you go JSON --> markdown instead of ApiItem tree --> markdown.
That's true. But in some cases I found that current JSON has not sufficient data to generate something like this:
Example Markdown
SetBar
Summary of SetBar method.
public SetBar(bar: Bar): void;
Parameters
- bar:
Bar
Returns
void
Without modifying ApiJsonGenerator
as far as I could go:
SetBar(bar: Bar): void
Access modifier (public, private, protected) is missing from current version of API JSON. Quick fix was, adding an additional property declarationLine
and I got wanted results.
// visitApiMethod method
// ...
declarationLine: apiFunction.getDeclarationLine(),
public SetBar(bar: Bar): void;
There are more places that would benefit from this property, like ApiProperty
etc.
if we could use a proper library (markdown-creator?)
json2md
was the first markdown library I came across. Looking at this library markdown-creator
, it's exactly what I wanted from markdown generator.
Lemme know if you'd want to collaborate on something like that.
Yeah, sure. api-extractor
still needs a little tweaks and bug fixes, so we can get useful data for generating markdown.
from rushstack.
Access modifier (public, private, protected) is missing from current version of API JSON.
Could you open a separate GitHub issue to track this (and any other limitations you encounter)? We are actively working on the documentation pipeline, including JSON schema improvements, and will prioritize this sort of issue. You can also feel free to create a pull request to fix any missing data issues in the JSON -- these are relatively easy fixes. :-)
Yeah, sure. api-extractor still needs a little tweaks and bug fixes, so we can get useful data for generating markdown.
Okay, maybe I can start by creating a small PR to add the basic skeleton of the Markdown generator, and then you could base your implementation on that, and give us suggestions? I don't really care what your Markdown output looks like, since we will treat it merely as a code sample (that we maintain and use for testing).
Looking at this library
markdown-creator
, it's exactly what I wanted from markdown generator.
I'm fine with that. FYI looking at the implementation, it is missing an escaping mechanism. For example, if you do this:
markdown.italic(' Here is my text');
Then you will get this (because of the space before H):
- Here is my text*
Or this:
markdown.italic('Avoid using an asterisk("*")');
Will print this (because the star is not escaped):
Avoid using an asterisk("")
This issue will probably be negligible for casual usage, but if you get serious about your documentation, you would want markdown-creator
(or some other library) to handle these problems. You could file a bug for them.
Does that sound like a plan?
from rushstack.
Could you open a separate GitHub issue to track this (and any other limitations you encounter)?
Alright.
I'm fine with that. FYI looking at the implementation, it is missing an escaping mechanism.
I will do a little research, what are other alternatives for markdown generation. We will see about that.
Does that sound like a plan?
Sounds like a plan π
from rushstack.
FYI I started work on this. Here's my PR branch if you want to follow along:
PR 322 Initial prototype of api-documenter tool
I'll update this issue when I've merged the first prototype.
from rushstack.
Hi @MartynasZilinskas - following up on this. The initial implementation is fairly close to being finished. I completed the main loop, and now just need to fill out all the different types of data. You can see an example of the current output on this web site:
https://microsoft.github.io/web-build-tools/api/
Let me know if you have any feedback about the layout.
from rushstack.
This should be fixed now.
from rushstack.
Related Issues (20)
- [rush] browser-approved-packages.json is not updated when dependencies are removed HOT 2
- [rush] `rush install --only .` installs all dependencies in the monorepo instead of only the dependencies in current folder/project HOT 10
- [@rushstack/terminal] Remove support for the legacy `IColorableSequence` objects.
- [heft-jest] In watch mode, changedFiles should only remove files that match before/after the run HOT 1
- [heft-typescript] Bound current directory in sys.watchFile and sys.watchDirectory
- [rush] Make `install` and `update` log package manager to a file in common/temp
- [api-documenter]
- [rush] Find rush.json location by using 'dirname' at most 10 times HOT 8
- [api-extractor] Allow generation of API reports per release level HOT 1
- [api-extractor] Internal Error: Unable to follow symbol for "Set" HOT 1
- [eslint-patch] Upgrade to ESLint 9 HOT 1
- [rush] Latest Node LTS security patch for spawnSync breaks rush on Windows HOT 1
- [rush] Medium - <CVE-2024-28863> -6.5 - Vulnerability in βtar6.1.15β
- [api-extractor] Union types extracted from declaration files are unstable
- [rush] tab-complete fails to complete project list after `--to` HOT 1
- [api-extractor] Better support for nominal types
- [rush] rush add -p <package> always installs as if `--all` is specified HOT 3
- [heft] `set-environment-variables-plugin` variables remain set in unrelated phases
- [rush] The source code address for the 'rush build' command.
- [rush] Cannot publish: getting ENEEDAUTH even though I'm already authenticated HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. πππ
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google β€οΈ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from rushstack.