vmware-tanzu / cartographer-site

Cartographer website

Website for Cartographer.sh

Prerequisites

• Hugo
  • macOS: brew install hugo
  • Windows: choco install hugo-extended -confirm
• Node
• Yarn

Serve

make serve

Visit http://localhost:1313

Generate a Release

to create a release copy of development use

make release version=v1.2.3

The new version should appear in the site and be the default.

Generating CRD Documentation

There is a tool, ./hack/crd.rb designed to autogenerate CRD documentation based off the content of our Go doc-comments in /cartographer/pkg/apis.

1. Check out cartographer locally, as a sibling of cartographer-site.

2. Ensure cartographer crd's are generated:

cd /path/to/cartographer
git co <revision you want to gen docs from>
make gen-manifests

3. Generate the site CRD reference:

cd /path/to/cartographer-site
make gen-crd-reference

4. review the changes to files in /cartographer/site/content/docs/development/crds/*.yaml
   1. Custom edits will be removed, so look for delta's that represent developer edits and roll those line's back

Note: the files in ./hack/crds contain configuration for which fields to replace or ignore.

cartographer-site's Issues

Edit button on docs pages is invalid

Since moving to cartographer-site, the Edit button is failing, it's still pointing to core cartographer.

Work HealthyCondition into troubleshooting docs

When healthRules were added to templates, new conditions were added. ResourcesHealthy and ResourceHealthy, appearing in owners (workload/deliverable) status and resources[n].status respectively. This isn't documented anywhere.

While #104 potentially deals with this by means of adding a reference to the documentation, the conditions surfaced in the owner are intended to help with troubleshooting, which has not been updated since this feature was added.

Troubleshooting doc should be improved to guide the user in assaying these new conditions.

Target of a link is missing

On Page: Authentication

There's a link override the service account name with the anchor #developer-selects-the-name-of-a-service-account-in-their-namespace, but a heading matching that anchor does not exist. (broken link)

Add search bar to docs site

As mentioned by Dodd Pfeffer here, the Cartographer documentation site lacks a search capability

Bug: Missing field and expression documentation in the selectors docs

This section needs to include an explanation of selectorMatchFields and selectorMatchExpressions

Remove patch versions from docs version dropdown

In the documentation, the dropdown should have v0.1.x, v0.2.x, etc, (rather than v0.1.0, v0.2.0) to make it clear that the docs are intended for all patch versions in the minor version line.

We should make sure to update the install link to the latest patch as releases are cut

Let's also remove v0.0.6 and v0.0.7

Latest docs need to use latest in urls.

A minor usability complaint.

Currently:

1. visit https://cartographer.sh/docs/latest/reference/gvk
2. you are directed to https://cartographer.sh/docs/v0.3.0/reference/gvk. (0.3.0 was the latest at time of writing).

AND

1. https://cartographer.sh/
2. click "documentation"
3. you are taken to https://cartographer.sh/docs/v0.3.0

This works and is nice way to link to the latest docs whatever they are.

The problem is that the versioned url becomes the one that chrome autocompletes. User's who use their chore search bar to return to documents might type:

google: carto doc gvk

which will take them to https://cartographer.sh/docs/v0.3.0/reference/gvk even when 0.3.0 is out of date.

Suggest:

the latest docs always use the latest version tag links when navigating amongst them.

Add a page for community sourced examples

As discussed in the June 1st community meeting, it would be great to have a page on the site with links to examples that are out there for cartographer.
It could contain examples such as the cartographer-catalog from TCE as a good example.
Ideally the page would have a simple edit button that would allow someone to open a PR directly and they could add the link to a repo and a short description of what the example includes.
This would allow showing the pluggability of cartographer as well as serve as a source of inspiration for many people on what they could do with cartographer in their own platforms.

Add yarn to Contributing: Development Dependencies

Bug description:

Yarn not mentioned in dev dependencies.

Steps to reproduce:

Please provide a set of steps to reproduce the behavior (example):

1. Run make lint

Expected behavior:

As a contributor, when I've installed the development dependencies, I should be able to run the make commands.

Actual behavior:

/Library/Developer/CommandLineTools/usr/bin/make -C site lint
yarn install
make[1]: yarn: No such file or directory
make[1]: *** [dev-dependencies] Error 1
make: *** [lint] Error 2

Document known Conditions (especially ResourcesHealthy) and how to consume them

Docs for Deliverable and Workload (e.g. https://cartographer.sh/docs/v0.4.0/reference/workload/) show that they have a Status containing Conditions. Similarly so for their Resources.Conditions.

The values of Conditions that may appear in this list (condition types, possible condition statuses and reasons) are not documented anywhere.

Whilst Condition itself a generic, core k8s concept, intrinsic cartographer behavior for conditions like Ready, or cartographer feature-specific behavior for conditions like Healthy are not, and we should enumerate the condition types that cartographer knowingly populates. This became painfully obvious when trying to understand how to meaningfully consume the outcome of a Template's healthRules.

In doing so, to allow them to be easily consumed, we should:

• offer clear explanation for the condition's meaning
• enumerate possible condition Status values, and what they mean in the context of this condition
• enumerate possible condition Reason values, and what they mean in the context of this condition, and where the next place to look

This may have some overlap with this existing doc: https://cartographer.sh/docs/v0.4.0/troubleshooting/

Sensitive terminology scan

Replace with Woke as per this pr

Docs need a copy to clipboard feature

Description of problem

When i see some useful base yaml in the docs, I often want to copy it, and i have to carefully select it (on some very long content) with my mouse

Proposed solution

Code blocks in the docs have a 'copy to clipboard' button

Additional Context

Plenty of simple Hugo examples exist, this should be simple

theme/content: head's title doesn't change in documentation

problem

just looking at open tabs our history, it's hard to figure out what a particular page from the documentation was about - they all have the same page title Documentation.

IIUC, that's coming from the partial here

cartographer-site/themes/template/layouts/_default/baseof.html

Line 7 in 278700b

<title>{{ if .Title }}{{ .Title }}{{ else }}Documentation{{ end }}</title>

where we do end up using .Title set to Cartographer for the landing page, but because of the lack of a .Title in the other contexts, it ends up always being the same "Documentation" title.

desired

I think it'd be great if for each page we had the title set to the root header (ala the h1 of that page's content), or something similar.

proposed solution

make use of Hugo's frontmatter for passing properties to the context? not really sure (I've used it a while ago, not sure what the best practices are)

Blog post card images should be clickable

When i visit the Carto Blog list at https://cartographer.sh/blog/ the blue heading is a link to the post, but I'm often inclinded to click the image above it. This should take me to the post as well.