Add read-the-docs support

[dholbach]

After talking to @stefanprodan I realised that versioned docs won't work easily with Gitbook, we'd also just have one free repo.

read-the-docs might be the way to go. Here's a WIP PR to get this into shape.

To run this, do:

# in top-level directory
make serve-docs

Todo list:

Content

• fix index
• use fonts we use in other places
• break up docs into subdirectories
• solve issues around over-flowing text boxes
• find solution for [bla.md#anchor] links (Add support for cross-referencing readthedocs/recommonmark#8)
• find solution for links in tables (links inside the table are not being proceeded by recommonark ryanfox/sphinx-markdown-tables#18)
• Remove the "next read ..." mention in the docs - this is in the RTD UI already
• factor in Hidde's feedback
• Helm Operator docs should be in a separate dir
• fix references from Weaveworks website

Build

• integrate https://hub.docker.com/r/ddidier/sphinx-doc/
• add linkchecker to find broken links
• hook up make test-docs with CI
• generally document how to use this
• hook up with release/build process (what do we need here? document how to publish a new release branch in readthedocs?)

Publish

• decide on project-name to use with readthedocs.io
• set up readthedocs.io account
• publish master
• pull in older releases
• link to docs from main README.md

[dholbach]

[dholbach]

In e3f3730 I made some changes to set up a new directory/index structure. This is just a proposal for everyone to get an idea. Let me know what you think.

[dholbach]

@stefanprodan in 2a30963 I added the build-in/serve-from docker, it's a bit messy, but there's instructions on how to to it in site/Dockerfile. Feedback/fixes welcome.

[stefanprodan]

@dholbach I've simplified the docs preview, all you need to do is run make run-docs from the root of the project.

Running make run-docs will:

• build the docs website inside the docker image
• create a docker image named flux-docs:latest
• run the docs website on http://localhost:8000/_build/html/index.html

PS. You can change the port binding with DOCS_PORT=8080 make run-docs

[dholbach]

Nice work, @stefanprodan! Would it make sense to have generate-docs and serve-docs targets? How are we going to deploy this?

[dholbach]

I just changed the directory structure somewhat... please let me know if I was jumping the 🦈 here:

.
├── development
│   ├── building.md
│   └── get-started-developing.md
├── faq.md
├── helm
│   ├── helm-integration.md
│   ├── helm-operator.md
│   └── helm-upgrading-to-beta.md
├── how-it-works.md
├── install
│   ├── get-started.md
│   ├── helm-get-started.md
│   ├── installing.md
│   └── standalone-setup.md
├── internals
│   ├── daemon.md
│   ├── fluxyaml-config-files.md
│   └── garbagecollection.md
├── introduction.md
├── requirements.md
├── troubleshooting.md
└── using
    ├── annotations-tutorial.md
    ├── fluxctl.md
    ├── git-gpg.md
    ├── monitoring.md
    └── upgrading-to-1.0.md

[stefanprodan]

@dholbach as describe here https://dont-be-afraid-to-commit.readthedocs.io/en/latest/documentation.html#readthedocs-org Read the Docs will watch your GitHub project, and build, render and host your documents for you automatically.

[hiddeco]

Would it be an idea to split the FAQ (fluxd / Helm op)?

[stefanprodan]

The docs structure looks ok to me 💯

[stefanprodan]

Yeah maybe the Helm Operator docs should be in a separate dir, this would make things easier when we'll have helm-op in its own repo.

[dholbach]

You guys think ahead! 👍

[hiddeco]

@dholbach I am going to file my final judgement of the new structure as soon as I have viewed a rendered version of the documentation. Hope to do this by the end of the day 🤞

[dholbach]

@hiddeco Luckily @stefanprodan made this very easy.... make run-docs and you're all set.

[hiddeco]

Thoughts now that I have seen the rendered views:

• 'Installing Flux' index should contain a section about installing Flux and the Helm operator at the same time, this could be on a new page or we can divide the 'get started' in two sections, one without the operator and one with.
• I think we should rethink some of the page titles, e.g. we have a top item 'Using Flux' with a 'child page' 'Using Weave Flux'.
• I think we should rethink some parts of the (naming of the) new structure, e.g, we have a 'introducing Weave Flux' index, but also a 'how Weave Flux Works' index. As a new user, I would expect the introduction to contain the latter, so we may need to rethink the naming, or merge parts.
• 'Internals' is something that would scare me away as a user, listing the more important features under this index (garbage collection and manifest factorization) will probably reduce the amount of people finding this information by themselves.
• ...more TBA (this is the result of a couple of minutes of thinking)

I think, to give people the best experience possible, we should maybe think out a structure without looking at what we currently have, but what we do want to tell people, and merge / rewrite things back into this structure so we revise all documentation at the same time.

[dholbach]

readthedocs/recommonmark#8 bites us for the following links:

faq.md:arguments reference](daemon.md#flags).
faq.md:[standalone-setup.md](./standalone-setup.md#using-a-private-git-host).
helm/helm-integration.md:You can use the [same annotations](./fluxctl.md#using-annotations) in
troubleshooting.md:[FAQ](./faq.md#can-i-change-the-namespace-flux-puts-things-in-by-default).
troubleshooting.md:   [./standalone-setup.md](./install/standalone-setup.md#using-a-private-git-host).
using/annotations-tutorial.md:it. `fluxctl` has the [`--k8s-fwd-ns <NAMESPACE>` option](../fluxctl.md#Connectingfluxctltothedaemon) for specifying the right
using/annotations-tutorial.md:interact with the deployments. First, please [install fluxctl](../fluxctl.md#installing-fluxctl).
using/fluxctl.md:- [`org.opencontainers.image.created`](https://github.com/opencontainers/image-spec/blob/master/annotations.md#pre-defined-annotation-keys)
using/fluxctl.md:using `flux.weave.works/ignore: "true"`. Read more about this in the [FAQ](faq.md#can-i-temporarily-make-flux-ignore-a-deployment).

[dholbach]

We also need to find a solution for overflowing text boxes.

[squaremo]

This is marvellous work, thank you @dholbach, and @stefanprodan and @hiddeco for pushing it onward.

[stefanprodan]

@dholbach regarding overflowing text boxes, I think we should use multi-line code blocks and we'll get a horizontal scrollbar.

[dholbach]

If we want to hook this up with readthedocs.org and serve the files from there, we need to decide on a project name - flux is taken.

[dholbach]

@bia Can you remind me of which fonts to use?

[bia]

Proxima Nova Montserrat and Roboto Mono

(Proxima Nova is not a free font)

[dholbach]

Proxima Nova and Roboto Mono

For monospace, right? In this order? Which other fonts to fall back to?

Which general font?

[bia]

@import url("https://fonts.googleapis.com/css?family=Montserrat&display=swap");
@import url("https://fonts.googleapis.com/css?family=Roboto+Mono&display=swap");

body {
  font-family: "Montserrat", sans-serif;
}

code {
  font-family: "Roboto Mono", monospace;
}

[dholbach]

Some links are also broken because of ryanfox/sphinx-markdown-tables#18 ...

[stefanprodan]

@dholbach maybe remove the links from tables? I don't think those are so important. Also I would setup readthedocs.org with weave-flux just for testing.