search

piotrwitek / utility-types

Collection of utility types, complementing TypeScript built-in mapped types and aliases (think "lodash" for static types).
MIT License
5.54k stars 230 forks source link

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

Open piotrwitek opened 6 years ago

piotrwitek commented 6 years ago

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:

IssueHuntBot commented 5 years ago

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

roottool commented 5 years ago

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 commented 5 years ago

@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. 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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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

roottool commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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

piotrwitek commented 5 years ago

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 commented 5 years ago

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

rahgurung commented 5 years ago

@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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 notifications@github.com 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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

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 commented 5 years ago

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

screenshot 2019-03-05 at 7 46 03 pm

roottool commented 5 years ago

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

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. capture2 capture3

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

piotrwitek commented 5 years ago

@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 commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

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

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 commented 5 years ago

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

IssueHuntBot commented 5 years ago

@issuehunt has funded $70.00 to this issue.

rahgurung commented 5 years ago

@piotrwitek can I have a look?

piotrwitek commented 5 years ago

Hey @gurungrahul2, You can take a look but I'm planning to investigate it myself first to find the right solution because all of the solutions proposed above are not acceptable.

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.

dosentmatter commented 5 years ago

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 namespace for Pick.

I tried typedoc myself and it works right off the bat. It generates static HTML pages. @piotrwitek, if you want less page reload, you can specify the --mode file and it will put it under a single Global page with anchors and links:

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

There are still small annoyances:

  1. Private types like _DeepNonNullableArray are visible unless you filter by "Public".

  2. Our @example is not formatted as a code block. This is our issue though, we can fix this by wrapping with ``` as see in bottom half of image:

  3. The search functionality doesn't seem to work for type aliases:

  4. typedoc seems to be for documenting internal code right now. This is an issue when you use the default --mode modules because your documentation will be split amongst different pages. It is still a problem when using --mode file because the export names will still use the internal naming such as AugmentedRequired in the image for annoyance#2. There is an open issue and PR to allow it to support documenting a single starting point at src/index.ts. They are suggesting --mode library.
    So the names showing up in the documentation will be the names of the types at declaration and not re-export. A workaround is to rename AugmentedRequired to Required and alias the built-in Required to something else to prevent name-masking. We don't have many renamed exports (export as) in src/index.ts.

The good stuff:

  1. Links to source code:

  2. Icons to document the API type with a legend at bottom of page. I wish they had a tooltip instead of a legend though.

  3. The search functionality exists. Not sure how to get it working though. But since we are aiming for single page, a find in page is sufficient.

  4. Both the jsdoc and TS source/type info is used in creating documentation.

  5. Bunch of other options documented in README and docs that might be useful.

piotrwitek commented 5 years ago

Thanks for the analysis @dosentmatter. To be honest I don't like typedoc, it has bad UX and is hard to use. I need some time to tinker with jsdoc2md to cook own solution.