Documentation and respective framework
arsdehnel opened this issue · 30 comments
Wondering if there has been any consideration around more of a framework for documentation rather than just readme files? I don't necessarily have a strong opinion on what tool might make sense, just wanted to see if there were any thoughts/plans/starters for it. To me a key to a successful tool is a good set of docs. I wouldn't suggest there would need to be everything documented in the framework right from the beginning but getting something setup so it's easy to add things as folks have time/desire would be nice.
This would be awesome. I have put some thought into it, but haven't had the time to get it all setup. I'll try and document the plans asap
Cool. I don’t have a ton of time but would be interested in maybe helping out with that.
I would potentially be interested in this too!
Started looking into this. Thinking about using somehting similar to mkdocs or hugo. Will try and post up an example soon!
Beautiful docs, https://node-postgres.com/
Would you guys consider switching to typescript? If so, then I can help you to introduce it, add build step and annotate the codebase. That will somehow solve the problem of documentation. I believe most of the IDEs (WS and VS Code for sure) pick up type definitions and show autocomplete even in javascript project (I don't even mention type check for typescript projects).
If you are not interested in switching to typescript, I can try to come up with @types/node-gitlab package, but that way it's harder to update types as you make changes in the codebase itself
Also, there is https://github.com/TypeStrong/typedoc which makes it possible to generate the documentation, once you have added annotations to your code
Cool!!! I thought about it initially, but had some trouble getting all the config stuff setup. I would def be interesting in trying it out though!
Hello!, I'm recomend Vuepress for the documentation.
I would like to contribute with this but I don't know if this is in development now.
Hey @diegoazh !! I was originally leaning to one of the two above options, but honestly all of them look pretty solid. If you'd like to build some docs in vuepress that would be great! Any reason you recommend vuepress over others?
Hi @jdalrymple, I recomend this tool for many reasons. It's simple, fast, markdown files, custom themes, service workers, google analytics, multilanguage support and all the power of VueJs inside of it.
It is new, I know, but it is very simple to use and it has a very fast development.
yea then im game!
Ignore the DNS redirect, but I threw together the fastest site possible using typedoc: http://arsdehnel.github.io/node-gitlab.
Probably a lot of options out there and ways to even make typedoc better but thought I'd just throw something out there.
Thats wicked! I've also threw a small one together using vue (See the PR above). Not sure what the best way forward would be. Anyone have any real preferences?
Is there a live rendering of that one? I missed that PR when scrolling through this issue otherwise might’ve just built that one and see how it is. I can pull it and build later when I’m back on my machine if it’s not published anywhere.
Not that it’s critical but do you know where this’ll end up publishing? GitHub pages seems like a fine starting point (or a home forever IMO) but are you thinking just under your namespace?
came across a *.js.org project just now while working on something else... maybe it would work to do gitlab.js.org?
Pulled down the vuepress branch and had a look. Did you write those .md files by hand or were they somehow generated? I'd hope for an automated method that uses typescript's annotations to build out docs such that there is no way to get the docs out of date with the code that it describes. That's the intent behind the typedoc setup that I played with and that seems really desirable IMO because nobody likes either a) writing jsdoc annotations in addition to typescript or b) having docs that don't match up with the actual code.
I don't have any weight in this discussion being a really limited contributor but I like the fact that typedoc is built for typescript and makes generation of docs super simple. I think we might hit limitations on their themes and control over templates (I have no experience here, just guessing) whereas something like vuepress is a full feature site generation tool that can be used to do anything we could dream up. But the ease of use/maintenance from the dev site is more important to me than feature rich site builder.
And to publish the docs (to answer my own question from above) I'd like to suggest we mirror this project onto gitlab.com (it is the GitLab API project after all) and use their GitLab Pages to host the site because their built-in CI processes can make the "publish docs" process much cleaner than GitHub's pages setup (IMO). And then I think we wire that gitlab pages site up to gitlab.js.org. But this is all just my opinion, I don't mean to come off as forceful or demanding, just throwing out a plan that makes sense in my head.
Given my use of this project I'd be happy to spend some time on making it better, albeit a pretty limited amount of time just do to life happening.
Pulled down the vuepress branch and had a look. Did you write those .md files by hand or were they somehow generated? I'd hope for an automated method that uses typescript's annotations to build out docs such that there is no way to get the docs out of date with the code that it describes. That's the intent behind the typedoc setup that I played with and that seems really desirable IMO because nobody likes either a) writing jsdoc annotations in addition to typescript or b) having docs that don't match up with the actual code.
Yea they were manually written :'( but doing a quick search, we could use them in combination. Typedoc to generate the docs, and vuepress to display them. This can be done through this plugin: https://www.npmjs.com/package/typedoc-plugin-markdown.
This way we get the best of both!
And to publish the docs (to answer my own question from above) I'd like to suggest we mirror this project onto gitlab.com (it is the GitLab API project after all) and use their GitLab Pages to host the site because their built-in CI processes can make the "publish docs" process much cleaner than GitHub's pages setup (IMO). And then I think we wire that gitlab pages site up to gitlab.js.org. But this is all just my opinion, I don't mean to come off as forceful or demanding, just throwing out a plan that makes sense in my head.
I completely agree. I've been wanting to do this for a while, but didnt know the best way to keep everything in sync. Also would have to enforce only using one place for issue management (github or gitlab, though github may have a better reach right now)
Created #440 to discuss things around the mirroring, thinking that's related but not absolutely required to be a part of this discussion.
I added typedoc-plugin-markdown to my branch and it generated a bunch of markdown just fine. I have no idea what vuepress is looking for and how it would generate a menu of any sort but it does seem quite possible to wire these two up. Do we have anyone that knows vuepress enough to help get this started? Otherwise I can keep reading docs and trying stuff I guess :)
Push it to a branch and ill give it a look later this weekend
Sorry, got sidetracked on another part of my project, I'll totally do this, just didn't get to it last week.
Updated my fork and created #448 that includes a couple commits. One for the package.json changes and one that has all the generated markdown (and a couple generated JSON files).
@jdalrymple with the rebranding you're working on do you have any plans around this documentation idea that has been rolling around? I can't figure out what the plan is here and so I sort of just left things as they were last fall. Feels like we need to decide if we want auto-generated docs included or if we're just wanting the "intro" stuff in a docs site and rely on vscode or other IDE to handle the specifics of the API. From there we can at least have a goal in mind on how the site should be put together and work from there.
@jdalrymple is there any documentation made anywhere for the above library describing methods with examples?
@katariarajat Beyond the basic docs in the README, no. However, for an understanding on a particular function/method, feel free to look at the core source, the code is pretty straight forward, it also closely follows the GitLab v14 documentation (with exceptions currently being worked on in #2258 )
Closing this for now, docs are quite low level, and with the typescript updates, should be pretty clear