Add table of contents to README

[zendern]

• What are you trying to do?
  Make our README more accessible and easier to browse and find things. It's also likely once we do this we might need to re-org the README so that the groupings make sense and what not so maybe do that if necessary.

• What feature or behavior is this required for?
  Helping folks easily and quickly navigate our documentation

• How could we solve this issue? (Not knowing is okay!)
  Maybe we just do it one off and update the PR template to make sure it stays up to date. And use this tool to do it.
  https://ecotrust-canada.github.io/markdown-toc/

Maybe we find a tool to add it as part of the CI process.

• Anything else?
  Have fun :)

cc @bhamail / @DarthHater

[NomadicDaggy]

Hi! Can I take this?

[zendern]

Hi! Can I take this?

Yup all yours

[NomadicDaggy]

I'm trying to get the local CI working to experiment with automating the toc generation.
Followed your guide @ .circleci/circleci-readme.md and ran into to non-descriptive error with circleci, maybe you've encountered it before? :

Running on Fedora 32, docker and circleci both installed natively, not from snaps.

[DarthHater]

@bhamail you mind looking ^

[deadlysyn]

@NomadicDaggy working another issue, with an older kernel than you, and didn't see this specifically... I did get ulimit -l/go runtime errors due to my kernel version which required me commenting the ci-lint bits in local-config.yml to test my other chagnes, but I'm wondering if something is going wrong with the sudo environment.

Just to eliminate a variable, would you mind trying to add yourself to the docker group and then just run the same command w/o sudo? That's what I'm doing.

[bhamail]

In addition to @deadlysyn suggestions, I notice you ran the first comand using sudo. FWIW, I do not need to use sudo on macos.

Also, the second command (&& circleci local execute...) would not be run with su privileges. If you really do need sudo, then you might need to also add sudo to that second command (&& sudo circleci local execute...).

Please let us know what you find!

[NomadicDaggy]

@deadlysyn added myself to the docker group and @bhamail no combination of sudo/not sudo works :(.

As an aside, there is a wonderful VSCode plugin that creates/updates the readme toc on save. But I guess it is too much to ask for everyone to use a specific IDE.

[NomadicDaggy]

Tried an older kernel (5.6.6.) since fedora keeps the previous one when upgrading. Still no luck...

[deadlysyn]

@NomadicDaggy sorry you are blocked 😿 i have been playing with this in a vm. got the same behavior by default (installed docker and circleci from vendor repo/git). one by one i commented each item in 'build' and get success with only checkout but no run steps...so it is either something about one of the run commands or an interaction between that/docker/fedora kernel. get a lot of journalctl spew during runs so still trying to decipher that, but this MIGHT let you simply comment all the sections beside checkout to add/test your specific pieces until we find a better answer.

[deadlysyn]

phew think i found it...looks like 32 changed some default firewall stuff that breaks container networking! i'm not sure how much you care about those defaults, but you can always change/revert.

i started uncommenting things one by one and noticed it was network commands that broke. this seemed to get it working for me:

$ sudo sed -i 's/FirewallBackend=nftables/FirewallBackend=iptables/g' /etc/firewalld/firewalld.conf
$ sudo systemctl restart firewalld docker

now builds work ok:

$ circleci local execute -c .circleci/local-config.yml --job build
Docker image digest: sha256:a435b026bd0f68c7af0a949d52bb011b37e5fe33a3b0d694c17293d60dd2d06e
====>> Spin up environment
Build-agent version  ()
Docker Engine Version: 19.03.13
Kernel Version: Linux d030de1e3727 5.6.6-300.fc32.x86_64 #1 SMP Tue Apr 21 13:44:19 UTC 2020 x86_64 Linux
Starting container circleci/golang:1.13
  image is cached as circleci/golang:1.13, but refreshing...
1.13: Pulling from circleci/golang
Digest: sha256:744e2d41272e1eb13549449e594f1eef12dd10e5b83901d43c0d1aa95688e8bd
Status: Image is up to date for circleci/golang:1.13
  pull stats: N/A
  time to create container: 279ms
  using image circleci/golang@sha256:744e2d41272e1eb13549449e594f1eef12dd10e5b83901d43c0d1aa95688e8bd
Time to upload agent and config: 471.370548ms
Time to start containers: 923.134454ms
====>> Preparing environment variables
Using build environment variables:
  BASH_ENV=/tmp/.bash_env-localbuild-1601606319
  CI=true
  CIRCLECI=true
  CIRCLE_BRANCH=main
  CIRCLE_BUILD_NUM=
  CIRCLE_JOB=build
  CIRCLE_NODE_INDEX=0
  CIRCLE_NODE_TOTAL=1
  CIRCLE_REPOSITORY_URL=https://github.com/sonatype-nexus-community/nancy.git
  CIRCLE_SHA1=d0e4e159397cdd08d11fee9d4a6837b6924a59fe
  CIRCLE_SHELL_ENV=/tmp/.bash_env-localbuild-1601606319
  CIRCLE_WORKING_DIRECTORY=/go/src/github.com/sonatype-nexus-community/nancy


The redacted variables listed above will be masked in run step output.
Enabling DockerHub rate limiting compatibility mode.====>> Checkout code
Making checkout directory "/go/src/github.com/sonatype-nexus-community/nancy"
Copying files from "/tmp/_circleci_local_build_repo" to "/go/src/github.com/sonatype-nexus-community/nancy"
====>> mkdir -p $TEST_RESULTS/gotest
  #!/bin/bash -eo pipefail
mkdir -p $TEST_RESULTS/gotest
====>> go get -u github.com/jstemmer/go-junit-report
  #!/bin/bash -eo pipefail
go get -u github.com/jstemmer/go-junit-report
go: finding github.com/jstemmer/go-junit-report v0.9.1
go: downloading github.com/jstemmer/go-junit-report v0.9.1
go: extracting github.com/jstemmer/go-junit-report v0.9.1
Success!

This is what gave me clue:

https://fedoraproject.org/wiki/Changes/firewalld_default_to_nftables

hth

[deadlysyn]

wow i'd forgotten about this, but am happy to knock out the TOC.