Docs are broken in several ways/places

[jacklinke]

What did you run into?

Trying to read the documentation to better understand this project, but much of the information is missing from pages or incorrectly formatted/garbled.

Why would it be helpful to document or fix this?

• It is difficult to understand
• Issues with docs that have existed for nearly a year make people think this project is defunct

To which section of the docs does this belong?

• Most of the content in the references is missing. For instance, only a handful of the models are noted, and none of the enumerations are listed. It appears that this content used to be in place at one time.
• Several links are broken (e.g. Available Settings section on https://dj-stripe.dev/usage/webhooks/ or the Extending subscriptions section of https://dj-stripe.dev/usage/managing_subscriptions/)
• Code blocks are incorrectly indented in some places, and not in others. For instance, the first two blocks on https://dj-stripe.dev/usage/webhooks/ are intended by 4 spaces (they shouldn't be), but the third block correctly omits the unnecessary spacing.

It looks like much of these issues crept in during #1451

[jleclanche]

I've updated the docs subdomains to redirect to dj-stripe.dev/docs - However that last one is looking broken at the moment so we have that to fix.

Next step is to get the docs to actually display correctly on the /docs path.

[abe-101]

Anyone know if the newly redesigned site ever supported multiple versions of the docs?

https://github.com/dj-stripe/dj-stripe.github.io/issues/7

[abe-101]

@jleclanche Do you have any insight into where dj-stripe.dev/docs is hosted and getting deployed from?

[jleclanche]

I think it's all https://github.com/dj-stripe/dj-stripe.github.io - possibly not the master branch

[abe-101]

I also want to point out the current state of the mkdocs.yml

https://github.com/dj-stripe/dj-stripe/blob/8727894baa30fdba68332d947a5c18ae6efe7e60/mkdocs.yml#L1-L86

the current deployment strategy is to copy this yml file into the docs repo and use it to deploy

it seem it was originally hosted in the docs repo https://github.com/dj-stripe/dj-stripe.github.io is very shy of the original one which includes a lot more (both a custom theme and a custom landing page)

[abe-101]

Thanks for the inputs both. I tried to get up and running building the other repo by following what the CI was doing, and managed to do that. I documented my steps here: dj-stripe/dj-stripe.github.io#5

However, when I did this, the generated documentation site looked like https://dj-stripe.dev/dj-stripe/master/ and not like https://dj-stripe.dev/ (all the fancy styling was lost).

@jleclanche I'm pretty confused by this statement:

The docs on the dev site are just using a custom theme for our docs generator and we can keep doing this.

When I search the repo for, e.g. "Stripe Made Easy for Django Developers" it comes up in HTML files, but not anywhere that looks like it could be built. How was this initial website created? It doesn't seem like the above is plausibly true, unless I'm missing something.

Assuming that it is at least somewhat close to true - where can I find that theme and how do i build the docs using it?

@czue You can find the theme and the text "Stripe Made Easy for Django Developers" in a previous git version (AFAIK GitHub won't search in git history)

See the repos for example at Mar 31, 2023: https://github.com/dj-stripe/dj-stripe.github.io/tree/e5ee3218fd66b4f7abef2f2f0ed581ebd815026a

You can see it all in the mkdocs.yml file from back then

[czue]

Good detective work @abe-101 and bless you for your efforts on sorting this all out!