Comments (33)
I got what you said on that comment, I'm starting work on it, will discuss further queries here. @piotrwitek
from utility-types.
I understand @piotrwitek.
I will check it and think about this solution.
from utility-types.
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?
from utility-types.
@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.
from utility-types.
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.
from utility-types.
@issuehuntfest has funded $20.00 to this issue. See it on IssueHunt
from utility-types.
@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!
from utility-types.
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.
from utility-types.
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.
from utility-types.
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).
from utility-types.
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?
from utility-types.
Now, I suppose manual based on source code changes.
Because I don't have an automatic solution.
from utility-types.
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.
from utility-types.
@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 ?
from utility-types.
I tried EsDoc https://esdoc.org/ but what it generated was a website version of README.md, not sources (as far as it looked).
from utility-types.
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.
from utility-types.
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 ?
from utility-types.
from utility-types.
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.
from utility-types.
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
from utility-types.
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.
from utility-types.
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.
from utility-types.
@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...)
from utility-types.
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
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.
from utility-types.
@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
from utility-types.
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.
from utility-types.
@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.
from utility-types.
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.
from utility-types.
Thanks a lot @roottool for your help. I'll pick it up after I'm back from vacation.
from utility-types.
@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.
from utility-types.
@piotrwitek can I have a look?
from utility-types.
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.
from utility-types.
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:
- Private types like
_DeepNonNullableArray
are visible unless you filter by "Public".
- 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:
- The search functionality doesn't seem to work for type aliases:
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 asAugmentedRequired
in the image for annoyance#2. There is an open issue and PR to allow it to support documenting a single starting point atsrc/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 renameAugmentedRequired
toRequired
and alias the built-inRequired
to something else to prevent name-masking. We don't have many renamed exports (export as
) insrc/index.ts
.
The good stuff:
- Links to source code:
- Icons to document the API type with a legend at bottom of page. I wish they had a tooltip instead of a legend though.
- 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.
- Both the jsdoc and TS source/type info is used in creating documentation.
- Bunch of other options documented in README and docs that might be useful.
from utility-types.
Related Issues (20)
- New utility type: Widen object's primitives
- New Type "AsyncReturnType"
- '_DeepPartialArray' is not generic.
- rfc: implement Dictionary<T>
- Module '"utility-types"' has no exported member 'Nullish'. HOT 4
- New Type "RequiredByValueExcept<T, ValueType>", "PartialByValueExcept<T, ValueType>"
- TypeScript: `DeepPartial` not working for union of string and string literals
- Add support for generic Event utility types
- Add a type "Swap<T, Replaced, Replacing> HOT 1
- Is there any reason for using yarn add instead of yarn add -D HOT 1
- Idea is Great, Why don't you commit your types utility to Typescript official built-in rather extra types? HOT 1
- $ElementType does not work with keyofStringsOnly TS option HOT 2
- Non Empty Array Type HOT 2
- Inconsistency with Assign docs HOT 1
- DeepPartial does not allow empty object for generics HOT 2
- Type Falsey doesn't include `0n` and `HTMLAllCollection`. HOT 1
- rfc: add DeepAssign HOT 1
- Is there any way to use these types without import 'utility-types' HOT 3
- add "has_property" and "has_value" type guards for objects HOT 1
- Allow for a AllUnionKeys 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 utility-types.