Use consistent docs/sources directory for technical documentation

[jdbaldry]

This is consistent with other projects like Mimir, Grafana, and Agent.

Signed-off-by: Jack Baldry [email protected]

[joe-elliott]

I'm not strongly opposed to this, but it is moving a lot of files and may break existing links. Any particular reason this is important?

[jdbaldry]

I'm not strongly opposed to this, but it is moving a lot of files and may break existing links. Any particular reason this is important?

Very fair. I don't know the repository too well to identify broken links but I can do some grepping for the old directory and files within it.

The primary reason is reduced cognitive load for technical writers and external contributors achieved by consistent structure across repositories.

[jdbaldry]

~I've not found anything with this script:~

#!/usr/bin/env bash

set -euf -o pipefail

function usage {
  cat <<EOF
Grep for any files in the docs sources to see if there are broken links within the repository

Usage:
  $0 <DOCS SOURCES DIR>

Examples:
  $0 ./docs/sources
EOF
}

if [[ $# -ne 1 ]]; then
  usage
  exit 1
fi

cd "$1"
files=()
while IFS= read -r -d $'\0'; do
  files+=("${REPLY#./}")
done < <(find . -type f -name '*.md' -print0)

function join {
  local -r separator="${1-}"
  local -r elems="${2-}"
  if shift 2; then
    printf %s "${elems}" "${@/#/${separator}}"
  fi
}

cd -
exprs="$(join ' -e ' "${files[@]}" $1)"
echo "Grepping with exprs: -e ${exprs}"

find . -name docs -prune -o -type f -exec grep -Hn -e ${exprs} \{\} \;

Edit: the previous version of this comment had a bug in the script that caused it not to match anything.

[ie-pham]

A few places where the path needs to be updated:

• https://github.com/grafana/tempo/blob/60948b757097dfb36eef70b8de8be81f0292c7d0/docs/README.md?plain=1#L3
• https://github.com/grafana/tempo/blob/60948b757097dfb36eef70b8de8be81f0292c7d0/.github/workflows/website-next.yml#L8
• https://github.com/grafana/tempo/blob/60948b757097dfb36eef70b8de8be81f0292c7d0/.github/workflows/website-versioned.yml#L11
• https://github.com/grafana/tempo/blob/60948b757097dfb36eef70b8de8be81f0292c7d0/README.md?plain=1#L17
• https://github.com/grafana/tempo/blob/60948b757097dfb36eef70b8de8be81f0292c7d0/README.md?plain=1#L1

[jdbaldry]

Thanks for the help @ie-pham. I've updated the places you found and have merged main to resolve the conflicts from the big directory rename.

[osg-grafana]

@jdbaldry, can you resolve these conflicts so the PR is in top shape?

[jdbaldry]

I am tempted to leave the conflict resolution to the merger because this will just fall out of shape if we don't merge immediately after.

[osg-grafana]

I am tempted to leave the conflict resolution to the merger because this will just fall out of shape if we don't merge immediately after.

Would you mind finding a volunteer to be the merger? Atm, the responsibility falls on a "room full of people" and is likely to linger in that state longer than otherwise.

[yvrhdn]

Nice cleanup, makes the docs folder simpler to work with :+1:

PR can't be merged because the CI action "Check kube-manifests & tempo-mixin" didn't report success (it doesn't run for docs changes). I'm just going to bypass branch protection and force merge.

[jdbaldry]

Thank you so much @kvrhdn. Keep an eye out for any oddness from the reshuffle and ping me if there's follow up clean up needed :)