New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add a web page with API documentation that will be automatically generated from the recent source code changes #30
Comments
@issuehuntfest has funded $20.00 to this issue. See it on IssueHunt |
I made API documentaiton webpage Contents and sentence are only in Please check it. |
@roottool that looks cool, I love it man 💙 Just a few small changes in would like to suggest:
Also we would need a readme with explanation how to update contents when API changes, workflow commands (run locally /prod build). I can take care of deploy commands as this will be deployed on github pages. Could you also create a PR. I'll also create a logo contest issue, with a logo it would look even more rad! Can't wait to see it live! |
Hey @roottool , great work, just wanted to ask are you still working on this? It has been inactive for 9 days, ping if you are on it, If not, I am taking up the issue. |
Not sure about @roottool solution, but it seems to me it's maintained by hand. I updated an original post with new requirements describing a proposal of a suitable solution for our case. |
I got what you said on that comment, I'm starting work on it, will discuss further queries here. @piotrwitek |
Sorry, I was busy this week. I didn't work it this week. I confirmed your suggestion. Thank you for a suggestion for how to create PR. |
Hey @roottool, no problem. My biggest concern is how do you update "API reference docs and examples" on your website, is it manual or automatic based on source code changes? |
Now, I suppose manual based on source code changes. |
I understand @roottool, so then please check the proposed solution here which is the solution I would like to have: #30 (comment) Unfortunately, a manual solution is not good for the maintainers of this project. Please think about it because if this is not possible to achieve with your solution then @gurungrahul2 started working on the automatic solution that we need. |
I understand @piotrwitek. |
@piotrwitek Can you give me an example of making a website from source? I mean how will be the overall representation of data, like I know we added JSDoc but I am confused. Are they going to show up all in a single page? Only those comments (formatted in nice way) are going to show up in website ? |
I tried EsDoc https://esdoc.org/ but what it generated was a website version of README.md, not sources (as far as it looked). |
Have you tried play with config in ESDoc? https://esdoc.org/manual/config.html Also I don't know ESDoc support typescript source files. The ones I linked have typescript support because they are using babel for parsing which supports TypeScript natively. |
You can easily confirm that by adding the missing comments and see if that
function is added to the generated site
…On Sun, Feb 24, 2019, 3:53 PM R. Gurung ***@***.***> wrote:
It has a plugin for Typescript, but it recognized only one function, are
you sure we documented it the right way and it is parsable into website,
saying so because @param <https://github.com/param> @returns
<https://github.com/returns> are not there in most comments, I think it
should be there, is it ?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#30 (comment)>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AAtHAyf6_m42lWvXGLtdIrPtmMnYZadsks5vQqdtgaJpZM4WveWK>
.
|
hey, lets try https://github.com/Microsoft/tsdoc with https://typedoc.org/ , I may need to make changes in comments but I will come up with a website soon. |
Hey @gurungrahul2 could you show me an example of what the results will looks like? What is main requirement for me is smooth scroll navigation like here: https://docsify.js.org/#/configuration?id=repo I don't want page to be reloaded like here (which is super awkward these days): https://typedoc.org/api/index.html |
I updated the previously created page. This site is created by React. After executing the commands you can see the site published with EditedI found some bug about routing and I fixed them. |
@roottool don't you still have to manually update contents? what we are looking for is to directly parse comments and convert them into a website. It's easy to convert markdown into a website but the problem is converting comments into markdown or comments directly into the website. |
No, it is necessary to manually write the description for the page apart from comments in the source file. |
@roottool you're site looks really nice, but there are still couple of issue I would like to address:
|
I tried updating the website.
I moved categories from right to left.
Typedoc only outputs HTML, CSS and JS that make up the website or a JSON file. Probably, this page will be helpful for you. |
@roottool thanks for your investigation 👍 What's the issue with I can see |
I see. This site's CSS is almost a default CSS generated by Typedoc. No, I don't try it yet. Because I don't know whether to proceed with website creation with Typedoc. |
@roottool I don't think custom CSS is a good idea, because it would require a lot of effort. I would prefer to use ready out-of-the-box solution like docsaurus. |
I checked creating This two ways have an one big problem if we use docusaurus. ---
id: intro
title: Getting Started
--- Currently, there is no plugin that automatically adds this header except for typedoc-plugin-docusaurus. In Addition, a top page using docusaurus is made up The easiest way I think is to use Typedoc. Last, I can't work on this issue because I will be busy from this week. |
Thanks a lot @roottool for your help. I'll pick it up after I'm back from vacation. |
@IssueHunt has funded $70.00 to this issue.
|
@piotrwitek can I have a look? |
Hey @gurungrahul2, Also I would like to see a working proof-of-concept before any real work on this issue starts so I can see that it's the right and working solution. Then I will open this ticket to accept PR's based on the proposed solution by me or if not I'll do it myself. Your best bet is to propose the solution first and then build POC. |
A negative of using babel based docgens is that we would have to maintain babel compilation of our source along with TS. Also, there are some caveats/missing features when using babel for TS. I see that we are using I tried typedoc --out docs --mode file src/index.ts There are still separate pages for index.html (our README.md is rendered here which is a nice feature), global.html, and "Externals" like There are still small annoyances:
The good stuff:
|
Thanks for the analysis @dosentmatter. To be honest I don't like |
I would be nice to have a nice API Documentation webpage with search functionality similar to Ramda: https://ramdajs.com/docs/
API documentation requirements:
A recommended solution is to parse source files (which now contains usage examples in JSDoc comments) to generate a markdown based static documentation website.
One way is to use a full documentation generator to generate a website from source files (I'm open to suggestions if you can find something but I guess TypeScript support will be required, maybe this: https://dotnet.github.io/docfx/).
Another way would be to use a JSDoc => Markdown transformer (like jsdoc2md) and then add some custom scripts to do the rest and use it as a page in a markdown docs generator like Docsaurus or Docz.
Additional alternatives to investigate:
The text was updated successfully, but these errors were encountered: