You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@annotator.apache.org by GitBox <gi...@apache.org> on 2021/01/06 00:07:05 UTC
[GitHub] [incubator-annotator] Treora opened a new pull request #101: Set up tsdoc markdown generation
Treora opened a new pull request #101:
URL: https://github.com/apache/incubator-annotator/pull/101
Taking a stab at #97. It seems to work, but suggestions/improvements welcome.
@tilgovi: you suggested [@microsoft/api-documenter](https://www.npmjs.com/package/@microsoft/api-documenter) may currently be easier to set up than tsdoc; I found this a bit of a hassle to set up too, with more configuration than I’d like, so feel free to suggest we give tsdoc another try if you prefer (also I’m not sure if the output would be better/worse).
From my commit message:
> It seems we manually need to run api-extractor before running
> api-documenter; hence the bunch of configuration files.
>
> The packages each get their own documentation in packages/*/api/docs (I’m
> not sure we need it per-package; if it could simplify configuration we
> could just as well put it all into a single folder).
>
> Ideally, the 'apache-annotator' meta-package would contain the
> documentation of all packages it exports. The "bundledPackages" option
> seems to be made for this, but when used I get a ‘not implemented’ error
> because of the `import * as … from …` syntax we use. (I already had to
> modify the original `export * as … from …` because of a similar error)
> I suppose we could leave it for the time being, and be satisfied with the
> documentation of the individual (non-meta) packages.`
If we merge this, a next step would be to run this build script from the website’s build script, and copy the results into the website.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-annotator] tilgovi commented on pull request #101: Set up tsdoc markdown generation
Posted by GitBox <gi...@apache.org>.
tilgovi commented on pull request #101:
URL: https://github.com/apache/incubator-annotator/pull/101#issuecomment-812977488
I took another try at enabling typedoc and it worked without much issue. Maybe things improved in the more recent releases, but I wasn't getting any of the errors I had been getting. I merged that up to master, so I'm going to close this.
As a separate thing, we can try to add the markdown plugin and then import the result into the website, but I left that out for now.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-annotator] Treora commented on pull request #101: Set up tsdoc markdown generation
Posted by GitBox <gi...@apache.org>.
Treora commented on pull request #101:
URL: https://github.com/apache/incubator-annotator/pull/101#issuecomment-769245893
> One apparent problem that should be solved: linking to items in other packages does not work yet.
I forgot about that during the call. I fixed it now, by having api-extractor throw the output from several packages into the same (temporary) directory, and unleashing api-documenter in that directory.
Documenting the meta-package still does not work, but documenting everything except the meta-package (using `lerna exec`’s `--ignore` option) seems equally fine as a solution.
I think this is ready to merge, next step then is automatically copying `/docs/api` into the website (I’m calling it a day now; @tilgovi feel free to continue with that if you like, otherwise I’ll get to it soon)
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-annotator] tilgovi closed pull request #101: Set up tsdoc markdown generation
Posted by GitBox <gi...@apache.org>.
tilgovi closed pull request #101:
URL: https://github.com/apache/incubator-annotator/pull/101
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-annotator] Treora commented on pull request #101: Set up tsdoc markdown generation
Posted by GitBox <gi...@apache.org>.
Treora commented on pull request #101:
URL: https://github.com/apache/incubator-annotator/pull/101#issuecomment-757024702
I pushed some documentation-in-progress in the [more-docs][1] branch. One apparent problem that should be solved: linking to items in other packages does not work yet. In that branch, the console ouput of `yarn docs` is full of messages like this:
> WARNING: Unable to resolve reference "@annotator/selector#TextQuoteSelector": The package "@annotator/selector" could not be located
Perhaps it would be easier and would suffice to get the problem with the meta-package fixed, if we accept to just only use that one for generating all the docs. But quite possibly the underlying cause is the same.
[1]: https://github.com/apache/incubator-annotator/tree/more-docs
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-annotator] tilgovi commented on pull request #101: Set up tsdoc markdown generation
Posted by GitBox <gi...@apache.org>.
tilgovi commented on pull request #101:
URL: https://github.com/apache/incubator-annotator/pull/101#issuecomment-812977513
I won't delete this branch, in case you need it. But if you have a local copy and/or do not need to keep this, please feel free to delete to keep the branches tidy!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-annotator] Treora commented on pull request #101: Set up tsdoc markdown generation
Posted by GitBox <gi...@apache.org>.
Treora commented on pull request #101:
URL: https://github.com/apache/incubator-annotator/pull/101#issuecomment-757024702
I pushed some documentation-in-progress in the [more-docs][1] branch. One apparent problem that should be solved: linking to items in other packages does not work yet. In that branch, the console ouput of `yarn docs` is full of messages like this:
> WARNING: Unable to resolve reference "@annotator/selector#TextQuoteSelector": The package "@annotator/selector" could not be located
Perhaps it would be easier and would suffice to get the problem with the meta-package fixed, if we accept to just only use that one for generating all the docs. But quite possibly the underlying cause is the same.
[1]: https://github.com/apache/incubator-annotator/tree/more-docs
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org