Add a web page with API documentation that will be automatically generated from the recent source code changes

[piotrwitek]

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:

• https://github.com/onury/docma
• https://github.com/docsifyjs/docsify/ -> looks nice and this TS project is using it so we might check their solution https://github.com/romakita/ts-express-decorators

[IssueHuntBot]

@issuehuntfest has funded $20.00 to this issue. See it on IssueHunt

[roottool]

I made API documentaiton webpage This is a API documentaiton webpage source code

Contents and sentence are only in src/Text/Contents.json and src/Text/TableOfContents.ts. "Table of contents" is modified by changing src/Text/TableOfContents.ts. Top page is modified by changing src/Text/Contents.json and src/Pages/Home/index.tsx.

Please check it. And I want to create PR because I want to use IssueHunt But I made it in another repository. Do you have an idea?

[piotrwitek]

@roottool that looks cool, I love it man 💙

Just a few small changes in would like to suggest:

• set max-width 800 on the body content + sidebar width, because it's hard to read on desktop
• sidebar is open by default (hidden on mobile only)
• TOC in the side bar could use a smaller font and grouping could be different, like this:
  • TypeScript utility-types
  • Flow utility-types
  • Deprecated

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. You can put all the source code in the /docs folder I'm open for suggestions!

I'll also create a logo contest issue, with a logo it would look even more rad!

Can't wait to see it live!

[rahgurung]

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.

[piotrwitek]

Not sure about @roottool solution, but it seems to me it's maintained by hand. If that is really the case I'm afraid we need something better, automatic, nobody would like to keep it at sync by hand.

I updated an original post with new requirements describing a proposal of a suitable solution for our case.

[rahgurung]

I got what you said on that comment, I'm starting work on it, will discuss further queries here. @piotrwitek

[roottool]

Sorry, I was busy this week. I didn't work it this week.

I confirmed your suggestion. I have an one question. What belongs to TypeScript utility-types? Does it include Operations on sets and Operations on objects contents?

Thank you for a suggestion for how to create PR. I will try to work it from tomorrow(Currently 10:40PM Japan Standard Time).

[piotrwitek]

Hey @roottool, no problem. Suggestions are not very important for now.

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?

[roottool]

Now, I suppose manual based on source code changes. Because I don't have an automatic solution.

[piotrwitek]

I understand @roottool, so then please check the proposed solution here which is the solution I would like to have: https://github.com/piotrwitek/utility-types/issues/30#issue-361592589

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.

[roottool]

I understand @piotrwitek. I will check it and think about this solution.

[rahgurung]

@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 ?

[rahgurung]

I tried EsDoc https://esdoc.org/ but what it generated was a website version of README.md, not sources (as far as it looked).

[piotrwitek]

Have you tried play with config in ESDoc? https://esdoc.org/manual/config.html It looks like you can configure to mix both source files and readme together.

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.

[rahgurung]

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 @returns are not there in most comments, I think it should be there, is it ?

[piotrwitek]

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 [email protected] 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 https://github.com/piotrwitek/utility-types/issues/30#issuecomment-466783825, or mute the thread https://github.com/notifications/unsubscribe-auth/AAtHAyf6_m42lWvXGLtdIrPtmMnYZadsks5vQqdtgaJpZM4WveWK .

[rahgurung]

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.

[piotrwitek]

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

[roottool]

I updated the previously created page. And I created a readme with explanation how to update contents when API changes.

This site is created by React. When you execute commands in how-to-deploy, gh-pages branch will be created by gh-pages.

After executing the commands you can see the site published with https://piotrwitek.github.io/utility-types/.

Edited

I found some bug about routing and I fixed them. If you check this page and find bug, teach me please.

[rahgurung]

@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.

[roottool]

No, it is necessary to manually write the description for the page apart from comments in the source file. I was sticking to my way. Sorry. So I tried typedoc. By simply executing one command, you can build a document page automatically using comments in the source file. Page sample We need to adjust CSS and modify example in comments.

[piotrwitek]

@roottool you're site looks really nice, but there are still couple of issue I would like to address:

• I would like to remove all API reference from README.md so it would contain only welcome page for the website
• API reference will be autogenerated using source-files -> each source file will generate a single markdown file that will be later rendered on the website as respective subpages
• side-menu is still a bit hard to use right now, I think something similar to docsaurus would be much better, where on the left you would select group (Operations on Sets, etc...) and on the right you would have types listing from that group (SetIntersection, SetDifference, etc...)

[roottool]

I tried updating the website.

I would like to remove all API reference from README.md so it would contain only welcome page for the website

I removed it.

side-menu is still a bit hard to use right now, I think something similar to docsaurus would be much better, where on the left you would select group (Operations on Sets, etc...) and on the right you would have types listing from that group (SetIntersection, SetDifference, etc...)

I moved categories from right to left.

API reference will be autogenerated using source-files -> each source file will generate a single markdown file that will be later rendered on the website as respective subpages

Typedoc only outputs HTML, CSS and JS that make up the website or a JSON file. Therefore, Markdown used on this website will only be README.md. I am assuming to use Typedoc, so I have no idea about this.

Probably, this page will be helpful for you. It is how to convert from JSDoc in Typescript to Markdown. Or there will also be a way to convert a JSON file which Typedoc outputs using a Python library.

I will only be able to fix the circle of this blue line.

[piotrwitek]

@roottool thanks for your investigation 👍 I have to be honest with you, that site doesn't look pretty at all ;)

What's the issue with example comment tag? Can't the source be somehow formatted? have you tried using (```)

I can see U and T is formatted correctly in the desc tag

[roottool]

I see. This site's CSS is almost a default CSS generated by Typedoc. So I have to customize a default CSS. I will modify CSS after I grasp your ideal and concrete site design. I am not a website designer so I don't know I can realize your ideals.

No, I don't try it yet. Because I don't know whether to proceed with website creation with Typedoc. But It will be able to fix by using it as U and T is formatted correctly in the desc tag.

[piotrwitek]

@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. The only problem to solve is to figure how to use: https://github.com/jsdoc2md/jsdoc-to-markdown/wiki/How-to-document-TypeScript I'm not sure how hard it is, I can check tomorrow.

[roottool]

I checked creating .md file with jsdoc-to-markdown. It needs a hacky fix. And other way, I checked that typedoc-plugin-markdown can create .md file as below.

This two ways have an one big problem if we use docusaurus. They are unsuitable for docsaurus. This reason is that .md file which is used by docsaurus needs a header as below.

---
id: intro
title: Getting Started
---

Currently, there is no plugin that automatically adds this header except for typedoc-plugin-docusaurus. Although we can't use it. Because it needs old Typedoc version. It depends on old Typescript version(2.8.8). I tried building with it but it had occurred a build error. Therefore It is impossible to achieve directly parse comments and automatically convert them into a website if we use docusaurus.

In Addition, a top page using docusaurus is made up.jsx file. We can't use README.md to the top page.

The easiest way I think is to use Typedoc. If you want a website like Ramda, I think we pay the cost like Ramda docs page source.

Last, I can't work on this issue because I will be busy from this week.

[piotrwitek]

Thanks a lot @roottool for your help. I'll pick it up after I'm back from vacation.

[IssueHuntBot]

@issuehunt has funded $70.00 to this issue.

---

• Submit pull request via IssueHunt to receive this reward.
• Want to contribute? Chip in to this issue via IssueHunt.
• Checkout the IssueHunt Issue Explorer to see more funded issues.
• Need help from developers? Add your repository on IssueHunt to raise funds.

[rahgurung]

@piotrwitek can I have a look?