Setup to build docs on readthedocs.org

[zaro0508]

This is to partially resolve issue #1098.

We plan to move sceptre docs away from hosting on a
cloudreach domain to
https://readthedocs.org/project/sceptre

This PR adds the file to build the sphinx docs on readthedocs.org

[ngfgrant]

What are the benefits of moving away from GitHub pages?

[zaro0508]

@ngfgrant github pages is markdown format while the sceptre docs is reStructuredText format

[ngfgrant]

Oh right - the docs are currently being served from GitHub Pages (the format of the content doesn't matter as it's all generated to html in the end).

[ngfgrant]

To change the url you just need to edit the CNAME file here https://github.com/Sceptre/sceptre.github.io/tree/master

Alternatively, just remove it and you can access the docs at sceptre.github.io

[zaro0508]

thanks @ngfgrant. can we just replace cloudreach domain in the CNAME with the domain you've setup @tarkatronic ?

[craighurley]

Alternatively, just remove it and you can access the docs at sceptre.github.io

I didn't realise that was an option. The discussion about registering a domain for the project was mainly focused on a domain for the docs. If the docs can be accissible from sceptre.github.io, isn't that good enough and removes the need for maintaining a domain?

[ngfgrant]

@zaro0508 yep that is correct. Alternatively, as Craig said we can just use the GitHub provided domain.

[zxiiro]

What are the benefits of moving away from GitHub pages?

One of the nice things that ReadTheDocs provides as a built-in UI and support for multiple versions of docs. Switching to GitHub pages would mean we lose that right?

According to https://sceptre.cloudreach.com/ on the bottom left, it loooks like CloudReach's Sceptre docs are hosoted through ReadTheDocs right now or am I missing something?

[ngfgrant]

@zxiiro we wouldn't be switching to GitHub Pages as we are already using it. We also maintain versioned docs already..

Sceptre docs are "hosted" at https://github.com/Sceptre/sceptre.github.io

[zxiiro]

@zxiiro we wouldn't be switching to GitHub Pages as we are already using it. We also maintain versioned docs already..

Sceptre docs are "hosted" at https://github.com/Sceptre/sceptre.github.io

Interesting. I guess I haven't seen a readthedocs theme deployment outside of readthedocs which was what threw me off. Good to know it's possible.

[ngfgrant]

I would leave this for now as there is nothing wrong or restrictive about the current set up.

[tarkatronic]

Alternatively, just remove it and you can access the docs at sceptre.github.io

I didn't realise that was an option. The discussion about registering a domain for the project was mainly focused on a domain for the docs. If the docs can be accissible from sceptre.github.io, isn't that good enough and removes the need for maintaining a domain?

The initial discussion around registering the domain was to get the GitHub org verified, and eventually to be able to become a verified publisher, specifically for the GitHub Action.

The domain itself can be pointed at either GitHub Pages or ReadTheDocs. That part doesn't really matter. Although I would still recommend using RTD, as a way to reduce complexity. That build process right now is managed by a series of self-authored scripts which could very easily break at any time, whereas using RTD is simply a matter of setting up a config and installing the application on GitHub.

I personally advocate for any tooling that can reduce complexity in a build pipeline.

[ngfgrant]

The initial discussion around registering the domain was to get the GitHub org verified, and eventually to be able to become a verified publisher, specifically for the GitHub Action.

The domain itself can be pointed at either GitHub Pages or ReadTheDocs. That part doesn't really matter. Although I would still recommend using RTD, as a way to reduce complexity. That build process right now is managed by a series of self-authored scripts which could very easily break at any time, whereas using RTD is simply a matter of setting up a config and installing the application on GitHub.

I personally advocate for any tooling that can reduce complexity in a build pipeline.

IIRC the factors around original decision for how we handled docs were:

• reduce "tooling sprawl"
• remove dependency on 3rd party service and any incompatible version changes (e.g. RTD v1 vs v2).
• the flexibility/control of having specific docs available (e.g. we wanted to keep some of the old v1 docs alive).

The scripts could break at any time, but in reality they haven't since they were published 2 years ago... famous last words eh?

Ideally, we would reduce tool sprawl further by bringing the CI/CD to GitHub too... but that is another story.

A side note having these sorts of suggestions is fine but I would say they add limited value. Thanks to me (and some others) bigger problems exist in Sceptre - such as useful error messages or more meaningful debug statements. If we have people that are engaged with the project it would be good to get stuck in to the core concerns rather than around the periphery.

[tarkatronic]

Ideally, we would reduce tool sprawl further by bringing the CI/CD to GitHub too... but that is another story.

We have definitely talked about moving to GitHub Actions! The complexity of CircleCI has been quite a frustration, especially in #1035. A lot of the problems I've had to deal with are very specific to CircleCI, and (in my experience) don't exist, or manifest the same, on GitHub Actions.

A side note having these sorts of suggestions is fine but I would say they add limited value. Thanks to me (and some others) bigger problems exist in Sceptre - such as useful error messages or more meaningful debug statements. If we have people that are engaged with the project it would be good to get stuck in to the core concerns rather than around the periphery.

I agree there are definitely improvements to be made in the core, but the tooling around the project is a place where people like myself, less intimately familiar with the core, can help immediately.

[tarkatronic]

The other goal here is to lend further legitimacy to the project; having an official domain (which is totally free btw) and that little verified checkmark wherever possible can tend to add to that. I know that things like that give me a little more confidence in projects when I see them.

Plus, selfishly, my employer only allows us to use GitHub Actions from verified publishers. So I'm hoping that the Sceptre action can become one of those viable for use.

[ngfgrant]

100% onboard for new domain and GitHub Action sounds very cool - hopefully we can utilise the existing Dockerfile?

[zaro0508]

Ideally, we would reduce tool sprawl further by bringing the CI/CD to GitHub too... but that is another story.

I'm all for this, just need to find someone willing to do it 😄

A side note having these sorts of suggestions is fine but I would say they add limited value. Thanks to me (and some others) bigger problems exist in Sceptre - such as useful error messages or more meaningful debug statements. If we have people that are engaged with the project it would be good to get stuck in to the core concerns rather than around the periphery.

Ideally it would be great to have people working on the most pressing problems. However in reality we do not get to dictate what people work on and everybody has different interests and skill sets. I just prefer to encourage people to contribute whatever they want and have maintainers determine its value and decide whether it's worth incorporating into sceptre.

[zaro0508]

replacing this PR with PR Sceptre/sceptre.github.io#9

[tarkatronic]

100% onboard for new domain and GitHub Action sounds very cool - hopefully we can utilise the existing Dockerfile?

The goal is that the Dockerfile in this project will be able to translate over with no problem. The only modifications are in #1035; in there, I have changed it to a multi-stage build, utilizing Poetry to install dependencies. In this way we eliminate the fragmentation of requirements specifications (setup.py, requirements/dev.txt, and requirements/prod.txt) and, with the multi-stage build, it will ideally generate a smaller image overall!

If you're referring to the sceptre-circleci Docker image, then we should actually be able to fully eliminate that and just use the default GitHub Actions runner images 🤞🏻 -- at least, that's the hope.

And I'm super excited to work on that transition, if I can ever get the Poetry work finalized and landed!