docs(i): Remove docs website

[ribiza]

Relevant issue(s)

Resolves #4655

Description

As of v1, docs are located and maintained in the docs repository. I've deleted the check-documentation workflow, which became obsolete as the CLI and HTTP references are surfaced via the docs repo too. One less action to run on PRs, and one less thing to regularly fix.

I've removed the make:docs actions and added them for reference to the docs repo. We won't need to re-generate them too often and, when needed, they will need to be updated in the docs repo anyway, not here.

We used godoc to generate package docs, but that is deprecated and doesn't work with the current defra. I've cleaned that too. The ticket on how to surface this package docs is sourcenetwork/docs.source.network#218.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.25%. Comparing base (96bb671) to head (c4c78c7).

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #5022      +/-   ##
===========================================
- Coverage    76.40%   76.25%   -0.15%     
===========================================
  Files          620      620              
  Lines        49038    49038              
===========================================
- Hits         37463    37391      -72     
- Misses        8517     8563      +46     
- Partials      3058     3084      +26     

Flag	Coverage Δ
all-tests	76.25% <ø> (-0.15%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 20 files with indirect coverage changes

---

Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 96bb671...c4c78c7. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[shahzadlone]

Question: what about man pages?

[ribiza]

Question: what about man pages?

Please correct me if I'm wrong: man pages are not included in a single binary (in fact, man defradb yields nothing); they must be installed by the user. If that's the case, I can't imagine a user would a) build them; b) install them, when the same help is available via -h and online.

There's a danger when new things are added, that they're always added on top. I've taken the chance here to see what we could simplify. I might be missing some context, but if my picture of how man pages work is accurate, they look to me to constitute just an extra step in the build process without adding value to the user experience.

[shahzadlone]

Please correct me if I'm wrong: man pages are not included in a single binary (in fact, man defradb yields nothing); they must be installed by the user. If that's the case, I can't imagine a user would a) build them; b) install them, when the same help is available via -h and online.

The user must install them correct, currently we have make docs:manpages (command/rule you deleted) and make install:manpages. One generates the man page docs and one installs them. At the moment as the PR stands you have broken half of the flow (i.e. the man page generation), so there is no point of having the install rule any more, regardless of the direction we take, either remove all of it, or keep all of it (open to making the flow more simpler and automated for user).

There's a danger when new things are added, that they're always added on top. I've taken the chance here to see what we could simplify. I might be missing some context, but if my picture of how man pages work is accurate, they look to me to constitute just an extra step in the build process without adding value to the user experience.

I strongly disagree specially with the not adding any value part, perhaps maybe because i use it a lot myself. My vim has a shortcut command that can open man pages for any tool/command word under my cursor, I and many other vim users are quite used to having man pages used like this within the vim buffers. Removal of man pages completely strips away a user experience feature I use.

[ribiza]

One generates the man page docs and one installs them

Aha, thanks, good to know!

I strongly disagree specially with the not adding any value part, perhaps maybe because i use it a lot myself. ... I and many other vim users are quite used to having man pages used like this within the vim buffers.

Thanks for clarifying that. So as I understand it, there's three prerequisites for using it:

1. you need to build from source (no compiled binaries/docker images), with all the complications it entails (ex. do you choose to build dev or a stable version? what is the latest version? in which (of the current 54) branch is the latest version?)
2. you need to be aware that a build will produce man pages under build/
3. you need to know that make install:manpages exists

We can debate how many people will really go through all this hassle when they are likely to only run a handful of commands and -h is an established way of peeking at help, but I think we can agree that all this is non-trivial for a random user. As far as I know, steps 2 and 3 are undocumented, so for this to be a feature that can be used, they need at minimum to be mentioned somewhere (and this would be exactly one of the things which I see the repo's readme perfect for).

I want to stress that I don't claim to have all the answers here and I'm happy for you to take over this PR and reshape the internal docs in the way the team sees fit. What is important to me is that it becomes clear that any public facing docs are not sourced from this repo -- which is the sense of deleting /website.

[ribiza]

Ah, I should add that, on my system, /usr/share/man/man1/ contains only .gz files. The current make install:manpages seems to copy all as single files, and just judging from the content of the man dir this doesn't seem to be the right practice. But again, I only seldom use man pages.