Fix documentation

[shaftoe]

[shaftoe]

@alexwaibel so I guess I should start fixing from here, right? https://staticman.net/docs/index.html

I list here a few ideas, please correct me if I don't understand correctly:

• relegate the "hosted version of the platform" bit to the end with maybe a disclaimer, like "in the past this was such and such, but now we officially encourage you to host your private Staticman instance via Heroku, we're not providing any support for the legacy hosted service at the moment"
• add a chapter at the beginning which displays the actual integration, maybe with a simple diagram showing the connection between the components (e.g. your site <-> staticman API <-> git repo). I think starting straight with instructions on how to setup GitHub repo is confusing
• explicitly restrict the setup for which we provide support form, i.e. self hosted Heroku instance + GitHub, and just mention that it's possible to use other integrations like GitLab or even running it with some container orchestration like AWS ECS, Kubernetes etc. but we don't provide support in that case

Please add/edit whatever you think makes sense or might help coming up with a decent draft, thanks

[LordAmit]

Umm, from what I understand (I only managed to setup Staticman yesterday) there are three versions of staticman

• v1 - deprecated, used to use the staticman as a collaborator
• v2 - Heroku based Github
• v3 - Heroku based GitHub / staticman-net GitHub application which is used without Heroku

Did I get it right? Because these are not discussed in documentation, and I picked them up from here and there from various websites and issues here. Since it is this confusing, maybe provide setup based quick-start steps in documentation considering the last two approaches. (edit: oh wait, maybe v2 is actually v3.. uh.. nvm, I am confused)

I like the second point, visualizing (through a flow / block diagram maybe) will definitely help.

[alexwaibel]

Umm, from what I understand (I only managed to setup Staticman yesterday) there are three versions of staticman

* v1 - deprecated, used to use the staticman as a collaborator

* v2 - Heroku based Github

* v3 - Heroku based GitHub / staticman-net GitHub application which is used without Heroku

Did I get it right? Because these are not discussed in documentation, and I picked them up from here and there from various websites and issues here. Since it is this confusing, maybe provide setup based quick-start steps in documentation considering the last two approaches. (edit: oh wait, maybe v2 is actually v3.. uh.. nvm, I am confused)

I like the second point, visualizing (through a flow / block diagram maybe) will definitely help.

You're close, but a few details aren't quite right:

• V1 - Original API, used webhooks, is deprecated but still supported for now since some users are presumably still using it

• V2 - API which uses tokens to authenticate with GitHub. Most stable version and what many guides are written for

• V3 - Newest API, intended to add authentication as a GitHub App rather than using a personal access token. Adds supports for GitLab as well.

All of these require some kind of hosting. Even V3 as a GH App requires that the application be hosted somewhere (we recommend Heroku). We definitely need better API docs and I'm hoping to leverage something like Swagger to help document this stuff. Having up to date API docs should go a long way towards clarifying all the endpoints Staticman offers.

[alexwaibel]

@alexwaibel so I guess I should start fixing from here, right? https://staticman.net/docs/index.html

Yes, this is a good place to start updating.

I list here a few ideas, please correct me if I don't understand correctly:

* relegate the "hosted version of the platform" bit to the end with maybe a disclaimer, like "in the past this was such and such, but now we officially encourage you to host your private Staticman instance via Heroku, we're not providing any support for the legacy hosted service at the moment"

I think we should stop mentioning the public instance in the docs all together. This instance is not being actively maintained and we offer no guarantees that we'll fix it if it ever goes down. No new users should be using this and as such I think it's best to leave it out of the docs. Anyone using that instance should immediately migrate to a self-hosted solution. I would write the docs as if self-hosting is the only option.

* add a chapter at the beginning which displays the actual integration, maybe with a simple diagram showing the connection between the components (e.g. your site <-> staticman API <-> git repo). I think starting straight with instructions on how to setup GitHub repo is confusing

Some kind of architecture and/or sequence diagrams would definitely be helpful. This would be a good addition to the docs.

* explicitly restrict the setup for which we provide support form, i.e. self hosted Heroku instance + GitHub, and just mention that it's possible to use other integrations like GitLab or even running it with some container orchestration like AWS ECS, Kubernetes etc. but we don't provide support in that case

I agree. I'd call out in the docs that the setup instructions are for Heroku + GitHub (I've never tried GitLab but I believe it works and the setup should be very similar to GitHub) and mention that Heroku is just one of many hosting options and that users can host on whatever platform they desire. We just use Heroku in the docs because that's what we've personally been using for hosting and it's the most streamlined setup at the moment.

[shaftoe]

@alexwaibel can you please review https://github.com/eduardoboucas/staticman.net/pull/11 ?

[shaftoe]

@alexwaibel can you please review eduardoboucas/staticman.net#11 ?

@alexwaibel thank you, I see you approved the PR.

I'm still confused about the dev workflow though: why is it not merged yet? do you need a certain amount of reviewers to approve it too? etc.

Thanks

[alexwaibel]

I'm still confused about the dev workflow though: why is it not merged yet? do you need a certain amount of reviewers to approve it too? etc.

Sorry, I forgot to click the merge button. It's fine for you to merge in your own PRs once they have at least one approval. I'll double check that the branch protections enforce this

[shaftoe]

Related PR: https://github.com/eduardoboucas/staticman/pull/371

[LordAmit]

I am really liking how it is turning out.

One suggestion: current deploy to heroku deploys v3 of staticman. Most of the documentation I see (tutorial,staticman.net) are based on either v1 and v2, and the references I find to v3 are in issues/commits. Maybe the "howto" should focus on v3 since it offers both GitHub/gitlab approach.

[shaftoe]

@LordAmit yeah I agree. We're improving staticman.net docs too, which by the way in my opinion should become the official user documentation resource, i.e. user docs there and dev docs here.

Given that I've found no documentation about v3 yet it means that either someone else provides or points me there, or I'd have to go through the codebase (which is not too big but it will take me some time obviously).

@alexwaibel also said he wishes to add support for Open API (ex Swagger), I don't know the effort needed for that though.

[LordAmit]

I believe this is the pull request which introduced major changes for v3 and also includes the most details https://github.com/eduardoboucas/staticman/pull/219

I am not quite sure why I was unable to setup v3 following this (or others). Some of the details are also missing there, like what prop means and why it is used.

@alexwaibel since I am very new to this repo and don't have much experience, can you please confirm that this is the correct link to find details about v3?

[alexwaibel]

@LordAmit I missed this before, but indeed that post is probably a good reference for the various APIs, though it may not be 100% accurate now given how old the post is.

If by prop you mean property in the routes, I believe that is used for the top level property block in your staticman config. In the case of the provided staticman.sample.yml the property would be comments.

I know this thread is old now, but I am hoping to tackle some doc updates here soon.

[alexwaibel]

Big documentation PR for this up now on the docs repo

[VincentTam]

The intention of introducing the v3 API scheme is due to the lack of Git service provider in v2's path element for POSTing comments:

/v2/entry/user/repo/branch/property

together with the request to support GitLab in #22. If you follow the discussion four years ago, you'll see that @zburgermeiszter proposed the current link format in his comment. That was supported by @ntsim, who authored #219 to address this feature request.

The rate limit issues about the v2/connect route #222 and #227 that inspired the proposal of using a GitHub App in #243 and resolved in #255 is another issue.

[lionxlife]

So regarding: Webhook URL: "{STATICMAN_BASE_URL}/v1/webhook" - e.x. "https://mystaticmaninstance.herokuapp.com/v1/webhook" in step 1, I'm already lost. How do I even get this? Signing up to heroku doesn't give you this link. Am I missing something?