[New Project] Confidential Containers Website

[surajssd]

Project Description

I have reserved a domain http://confidentialcontainers.org/ for the community. We should work towards creating a website for hosting blogs, release notes, documentation, demos and general landing pages. GH is pretty barebones in this respect.

Objectives

• We need to have a single place to host documentation of all the sub-projects.
• We need place to post blogs.
• A place to post release notes.
• Apart from documentation, in the k8s style to increase project adoption we also need sections like Getting Started, Concepts, Tasks, Tutorials and Reference.
• The developer docs can live on GH for each project.

[fidencio]

@surajssd, https://github.com/confidential-containers/confidentialcontainers.org has been created and you've been set as an admin there.

[portersrc]

@surajssd thanks again for initiating this work.

I temporarily put a sphinx-generated prototype on my github page here. It's showing some of the docs from the confidential-containers repo. It shows how you can link to other projects (e.g. operator and guest-components) and incorporate rustdocs (e.g. for image-rs).

A note (in favor) about the effort and changes required here: As long as we put the current docs for each repo in a top-level docs/ folder, this approach mostly "just works." When sphinx runs, it generates the webpages from the .md or .rst files it finds there. I did this for confidential-containers, operator, and guest-components and then strung them together to show how to form a single website. This prototype also reuses the markdown files nearly as-is. Sphinx can incorporate versioning or other niceties down the line.

All of your objectives make good sense to me. Responding to each in the context of this prototype:

We need to have a single place to host documentation of all the sub-projects.

Github pages can do this. It's a little awkward, because it requires us to push the generated website files to the repo (e.g. here). Those probably shouldn't be under version control, but it's simple to solve or ignore.

We need a place to post blogs.

This can be linked to or directly incorporated into this kind of sphinx approach. Example of the former: Use whatever you want and link to it from the sphinx-generated docs. Example of the latter: Write the blog in .rst or .md in one of the docs/ folders that sphinx uses to generate the site.

A place to post release notes.

The release notes are already captured, so this is "free" with sphinx.

Apart from documentation, in the k8s style to increase project adoption we also need sections like Getting Started, Concepts, Tasks, Tutorials and Reference.

Similar to release notes, we can use what we already have and add more, e.g. guides.

The developer docs can live on GH for each project.

I strongly agree with the idea of repo-specific docs. Top-level confidential-container docs can link to those projects, e.g. linking to operator or guest components docs.

[fitzthum]

I temporarily put a sphinx-generated prototype on my github page here. It's showing some of the docs from the confidential-containers repo.

This looks really cool. I guess the jury might still be out on exactly which tool we want, but Sphinx at least seems feasible. At some point we should tweak the ol' cascading style sheets to stick our logo in there and make it look a bit less like the Python docs.

This does reveal that we have a long ways to go with the content and organization of docs themselves. For instance we don't have a clear separation between information for developers and information for users. That is mostly orthogonal to this mechanism, though.

How flexible is the indexing for Sphinx? Will it always create the hierarchy of pages from the directories it is pointing to or can we override the structure to organize things differently? I ask because in the example site the guides section is somewhat hidden. It also feels circuitous to get to the individual repos and to the rustdocs. Either way, this seems like a very reasonable approach.

[portersrc]

Hi @fitzthum, thanks for the comments. Addressing them:

0. "Lookin' good, could look better." --yes

1. "The jury is still out on whether to use sphinx." --yes. As part of the bake-off, I spent time looking at mdbooks (@larrydewey's suggestion). mdbooks seems to look at the problem of documentation through a book lens first (as opposed to, say, an open source project lens). For example, the rust-lang book is in mdbooks; Linux kernel docs are on sphinx. My general takeaway is that mdbooks would also work. @surajssd may look at Hugo and have a nice approach there, too.

2. "We could refresh and reorganize the content." --bigyes. I didn't spend time with this, but this is a major reason to generate docs in the first place (as opposed to loose .md files throughout the repos).

3. "How flexible is sphinx's indexing?" --This is probably a strength of sphinx. The little prototype assumes the docs for each repo are built separately and linked together. But we could clone the repos and move everything into a top-level docs folder before sphinx-building if we want. Concretely, you have to tweak the toctree in index.rst to tell sphinx the structure you want, e.g. here.

[surajssd]

Hey folks, I got a basic website running, although it needs a lot of work but here is the code: https://github.com/surajssd/coco-website. You can see it locally by checking out code and running hugo serve.

The website uses theme called docsy which is used by a lot of cloud native projects. So for a k8s user this will feel right at home.

Here are some of the screenshots from the local run:

[fitzthum]

The screenshots look good. Is there a live version we could poke around on?

[surajssd]

Nope not yet. But, I am, working on it right now.

[surajssd]

So Chris and I spoke about this and decided that I take a stab at the initial set up. I was able to create a working website and the code is here: confidential-containers/confidentialcontainers.org#1. It also has instructions on how to test it.

I think we can move the conversation to this PR and close this issue?

cc: @fitzthum @portersrc