Sceptre: Breakout docs in to their own repository

[ngfgrant]

CONTEXT

Our docs are currently part of our core repository and part of the deployment process, which is not entirely necessary. I'd like separate the deployment of the documentation from the deployment of the code so that one is not constrained by the other. There is a decent amount of documentation to create and update. Currently, the deployment process is a bit verbose too, we currently use Jeykll and deploy on to a S3 bucket in Cloudreach. We could simply utilise Github Pages within the new repository to host our documentation and simply the deploy process.

DONE WHEN

• A new repository is created with the sceptre-docs as they currently stand.
• Sceptre docs are removed from this repository.
• sceptre.cloudreach.com is configured to point to GitHub Pages of the sceptre docs repo.

[rdkr]

I'd prefer to explore Read the Docs over continuing with a more DIY approach using GitHub Pages. It:

• provides documentation versioning support out of the box, although I'm not sure the current git tags will work with this immediately, as the v tag prefix may not be PEP 440 compliant.
• requires no deployment, just merge to version branch. This also prevents needing a new repo, which I can see being at least more work or possibly troublesome to ensure docs are merged along with features and from a doc versioning perspective
• familiar and more navigable default theme, with subheadings in the navigation sidebar

I'm happy to look into this further as an alternative to this issue.

[ngfgrant]

Hey @rdkr

Yeh I agree that a more streamlined development and deploy solution needs to exist. There are effectively three types of documentation that we need consider:

1. "End User" Documentation - tutorials, guides, etc.

2. API / Technical Documentation - currently generated by sphinx from inline code comments.

3. General Project Documentation - currently, a mix of .rst files including: README, CONTRIBUTING, HISTORY, AUTHORS and the GitHub Wiki for the Roadmap.

End User Docs

Currently, when a PR is merged into master, a build is triggered in Circle CI and there is even a setup where it can deploy and release to PyPi automatically (assuming tests pass). However, I'd like the "End User" docs to be able to move faster and not require a version release of Sceptre. This will effectively allow the community to submit tutorials etc without the same release burden that currently exists.

Recently, a number of issues have been created/comments made about typos in the docs. I think a reasonable QA step would be to have some form of spell checker run against the build of the "End User" docs. I also wouldn't want to abandon the current development Gitflow workflow we have. Although, I would be willing to forego an issue creation in place of a _good_ commit and pull request message.

I'd also like to reduce the tooling used throughout the project where possible. For example, the docs are currently hosted in S3 in an account somewhere. We can easily remove the need for S3 by using GitHub Pages, a free service we are already using.

Technical Docs

To complicate the situation slightly, the source for the API docs are inline with the code. When the docs are built/deployed we will want to grab the code comments so that the API docs that are published are up to date for latest. It shouldn't be too hard to do this, but we will need the flexibility to do this. We utilise tags in the main repo and when building the docs in the new repository we can utilise tags to equate.

Project Documents

Project docs will remain on GitHub. They are potentially due a refresh with a focus on clarity about how to get started and pointing people in the right direction. There will be a more obvious link to the Roadmap on the Wiki.

Solutions

In other projects we have used Gitbook, effectively a static site generator for docs, to good effect, which gives:

• good-looking out the book styling,
• host anywhere, GitHub pages probably preferred as it is simply a merge to the doc branch to make live. Also keeps everything in one place.
• no need for further external accounts
• built in local dev environment which is _very easy_ to run
• version link to tags or branches within docs repository

However, in this case I am not sure we need to use Gitbook, or ReadTheDocs.

We could ditch Jekyl completely and use Sphinx exclusively for documentation. There is a nice theme which is styled in the format of ReadTheDocs (https://sphinx-rtd-theme.readthedocs.io/) - which I agree is a more aesthetically pleasing layout.

The setup would look like:

• New GitHub repo sceptre-docs
• Move across the existing docs folder
• Setup repo: protected branches, PR requirements, hooks to CircleCI etc
• Change any .md files into .rst
• Write/modify script to build the api docs from github.com/cloudreach/sceptre.
• eventually change CNAME to point to GitHub Pages.

The documentation contribution flow would then look like:

• contributor forks sceptre-docs.
• contributor makes changes
• With good commit message (message _and_ description) open a PR.
• Address any requested changes and code is merged to master.
• Since we are using Github Pages the changes are instantly "live", once merged.

We will probably need to think about a change log and some form of tagging convention.

[1oglop1]

I do not really see the reason in splitting the docs into separate repository.
as @rdkr pointed out RTD should be good enough option because they support sphinx and documentation versioning, and since they host so many docs for other projects.
example: http://www.writethedocs.org/guide/ Which we can certainly use and benefit from it.

@ngfgrant there is info about doc versioning
http://docs.readthedocs.io/en/latest/versions.html

[ngfgrant]

Hey @1oglop1

Where to host of the documentation, is not the primary issue with this ticket. Could you also elaborate on not seeing the reason for splitting out the docs based on what has been said, so that I can try to address the main concerns you have?

The main goal is to be able to iterate the docs, specifically end-user (non-API docs), without the same burden currently imposed by:

• the contributing guidelines,
• building the code,
• running a full test suite,
• bump and deploy with documentation-only changes.

It is entirely possible to add a step to main sceptre build process to fetch and bundle the docs from a separate repository so that users are able to access the documentation locally, should they wish. If we tag the documentation appropriately then we can also ensure that the docs that are bundled are not just the latest.

On the point of whether to use RTD service: the main benefit of the service is the "attractive"/familiar UI. Beyond that, it limits what we (will) need in terms of build flexibility. It also only provides an interface to versions of documentation via either Tags or Branches, in that respect, it doesn't solve the potential issues we have with versioning; as in we still have to control documentation versioning ourselves. I am 100% for using the RTDs theme for Sphinx but actually using the ad-supported hosted-service provides us with a little or negative benefit, compared with something like GitHub Pages.

[webknjaz]

@ngfgrant it's entirely possible to use @travis-ci for docs only without separating them into a detached repo and even restrict it to run only tagged commits for example. There's also a Pages deployment provider I wrote, which takes care of putting html into gh-pages and is configured in declarative manner right from Travis CI config.

[1oglop1]

Just an addition - bare in mind that separating the repositories will bring a lot of side development overhead which is not really necessary to have given the size of project.
Another advantage of RTD it does build the docs for you.
I'd go for a simple version schema to cover the docs - dev, latest stable, few previous versions.

[ngfgrant]

Hey @webknja - thanks for joining the conversation. At the moment we aren't looking to move from CircleCI, it currently does what we need including recognising tagged commits.

@1oglop1 - Yep there would be some admin that doesn't currently exist for the maintainer. I think I've addressed the points on RTD and builds above.

As an aside, and more of a note to myself, I will need to check if there are any CR branding things we need to consider regarding docs theme.

I guess as a further bit of context - it is likely that the project will become a multi-repo project with the introduction of multi-cloud support, which admittedly isn't going to be until version 3. I am happy to put this issue on hold until then and keep the status quo. Although, we a still left in a place where updating documentation is a bit clumsy and tied to sceptre version releases. Based on feedback documentation is still the thing people think needs most improved across the project and we need to find a better way of allowing people to contribute easily.

[webknjaz]

My point was not about moving to Travis completely, but if you wanted to separate docs builds it would be a perfect place to do so.

[rdkr]

The main goal is to be able to iterate the docs, specifically end-user (non-API docs), without the same burden currently imposed by:

• the contributing guidelines,
• building the code,
• running a full test suite,
• bump and deploy with documentation-only changes.

It is entirely possible to add a step to main sceptre build process to fetch and bundle the docs from a separate repository so that users are able to access the documentation locally, should they wish. If we tag the documentation appropriately then we can also ensure that the docs that are bundled are not just the latest.

These goals seem like they are achieveable by adding a step in the process to check "does this commit only touch docs/*" before continuing or not with the rest of the automated build, test, deploy process.

For me, the greatest downside of the two repo approach is not a technical concern but instead the more complicated experience for code contributors who would have to update two repos and for the mainainers who must ensure parity of PRs and that code contributions have corresponding doc updates in another repo. The size of this project is not sufficient for this extra burden to be worthwhile right now.

On the point of whether to use RTD service: the main benefit of the service is the "attractive"/familiar UI. Beyond that, it limits what we (will) need in terms of build flexibility. It also only provides an interface to versions of documentation via either Tags or Branches, in that respect, it doesn't solve the potential issues we have with versioning; as in we still have to control documentation versioning ourselves. I am 100% for using the RTDs theme for Sphinx but actually using the ad-supported hosted-service provides us with a little or negative benefit, compared with something like GitHub Pages.

Could you expand on the issues we will have with build flexibility? I suggested RTD as it would allow for any new docs-only PR for be merged into master and to the latest tagged release branch and to be automatically updated on RTD (no need to deal with the current deployment process or to create a new one with GitHub Pages). As new versions are released, we stop merging new docs into the previous latest version, instead merging into master and the new latest instead. This seems like a simple way to ensure we have updateable and up to date docs, but I may be missing some context here?

Finally, I think we are all in agreement regarding the theme and use of sphinx. The PR referenced in 1oglop1/sceptre earlier in this thread is work @1oglop1 and I have done to bring the entire docs into sphinx using RTD, so even if this issue is on hold for discussion I suggest we open another issue so that we can PR those changes (or @1oglop1 can just PR now if we're happy with that).

[ngfgrant]

Content of docs will remain in core repo for now. Will move the static site out to another repo which will use content from sceptre from this repo where necessary. Closing for now.