request: Proposition for static documentation

[pelletier197]

Is your feature request related to a problem? Please describe.

This is less a feature request than a proposition. I have implemented a documentation generator for GraphQL called Magidoc, and I am trying to bring this into open source projects in order to get some feedback and get the user-base to grow. I came across your project in my research.

Describe the solution you'd like

Basically, I noticed you didn't have Github pages set up yet, so I propose to implement an auto-generated GraphQL documentation for this project that would be hosted directly into the Github Pages. This could contain an auto-generated API Reference and whatever else you like in fact.

I don't mind doing the whole thing and opening a PR, or letting you try it out and give me feedback about what you liked and disliked.

In the end, it's just a proposition, so no pressure at all if you're not interested. Thank you!

[favna]

I'll keep this open and consider it later. Right now I'm planning a full rewrite away from type-graphql as I want to upgrade to GraphQL 16, once that is done I'll revisit this proposal.

[favna]

So I've finally been giving this some thought and what bugs me most is how I'd host this. Ideally, I'd want to host it on https://graphqlpokemon.favware.tech/docs but that would mean hosting the files on my VPS, which would mean I'd need to have some way to push the generated files to my VPS whenever the public API is updated (hosted on the same VPS). On the flip side, hosting it on GH Pages is programmatically the easiest but doesn't offer an excellent domain like the above.

[pelletier197]

I'm not aware how you could host this on your VPS and push it on changes. Certainly something that is possible if you're able to do it manually, but you would know better than me.

For GitHub pages, you can actually use a custom domain name if you wish. See GitHub documentation.

This is what I do for my own documentation. https://magidoc.js.org

You can see how I did here, but if you need help, I'll be happy to help you.

[favna]

Tried giving it a shot myself. Setting it up to deploy to GitHub Pages through a gh-pages branch.

I'm having an issue with website.options.siteRoot.

I initially had it set to /favware/graphql-pokemon as per the instructions on https://magidoc.js.org/deployment/github-pages however then GH directed the deployment URL to https://favware.github.io/favware/graphql-pokemon/introduction/welcome whereas the valid URL is https://favware.github.io/graphql-pokemon/introduction/welcome (without the org in there again. Problem then is that the CSS and JS on that URL completely breaks.

I changed the website.options.siteRoot to just /graphql-pokemon but as you can see on https://favware.github.io/graphql-pokemon/introduction/welcome the site is still broken.

Eventually I'll make a CNAME for graphql-pokemon.js.org but for now I want it functional on the regular GitHub Pages URL.

Any help would be appreciated.

[pelletier197]

For sure. Thanks for the feedback and for trying it out. I'll check your PR as soon as I get some time.

[favna]

For sure. Thanks for the feedback and for trying it out. I'll check your PR as soon as I get some time.

There is no PR. I committed it directly to the main branch.

On another note, I'm not sure what the CLI is doing installing dependencies but I'm not very fond that it doesn't support Yarn v1/v3 and defaults to npm because it cannot find pnpm. Vendor locking package manager isn't best practise over all, but you really should add support for Yarn v1/v3 to the CLI. You can detect yarn presumably in the same way you detect pnpm (assuming you check if it's in PATH) and you can check the Yarn version by reading the packageManager field in package.json (it is possible the key doesn't exist as yarn v1 didn't use it). In my case that field is: https://github.com/favware/graphql-pokemon/blob/main/package.json#L135

[pelletier197]

Yarn was supported before, but I removed support for it because it's behavior was unpredictable with what I was doing with it. I will try to re-add it eventually.

I'll try to open PR tomorrow to fix your problem. Thanks for the details 🙂.