website: Make latest release (1.7) be default manual

[wader]

Fixes issue with confusion about features that has not been
released yet.

Move deveopment manual.yml to dev/manual.yml
Symlink manual.yml to v1.7/manual.yml
Refactor to share history header with links to other manual versions.
Change man.test and man page generation to use dev/manual.yml

Related to #3078 #3127

[wader]

Looks like this:

Tested locally doing jq/docs$ pipenv run python3.12 build_website.py and serve output directory using this Caddyfile:

{
	debug
}

http://localhost:3000 {
	root /jq/* output
	uri strip_prefix /jq
	file_server
}

[wader]

Made these same and absolute for all for less maintenance work and so that links are correct at both /jq/manual/ and /jq/manual//

[itchyny]

The /jq looks like the --root and the links don't work locally?

[wader]

Wops i messed up the markdown. It was suppose to say "...are correct at both /jq/manual/ and /jq/manual/<version>/". If we want to use a symlink to point /jq/manual/ to current release then that manual will be accessable at two locations so ../ will not work.

With the caddy config that maps /jq/<path> to <docs output root>/<path> (same as https://jqlang.github.io/jq/) links work fine for me locally. Or did you mean something else?

I think we want to keep /jq/manual/ working and not break links?

[itchyny]

As mentioned in docs/README.md and manual, we can specify the root path with --root to make links working with the output/ dir, serving with Python easily. So I think the links don't work locally. But the --root is a mess, I forgot why I couldn't make links work without this option, so you can cleanup the option.

[wader]

Ah i see, didn't know. I fixed the link to be relative to root now so i think we can keep it for now.

[wader]

I wonder what to do about jqplay links in the dev manual that won't work 🤔 add some warning somewhere or make jqplay version-aware? (might confuse ppl also)

[itchyny]

This is nice. Thank you!

My slight concern is the abbreviated name dev in the path, but I think that's ok. BTW should we consider follow the trend of inclusiveness and change the default branch name? If we choose develop, I'd like to align the path of the manual, but if main, I don't care.

[wader]

This is nice. Thank you!

Yeap hope it will address some confusion

My slight concern is the abbreviated name dev in the path, but I think that's ok.

Same as branch name might be good? but ok to merge this now as is and rename later if we decide to rename default branch?

BTW should we consider follow the trend of inclusiveness and change the default branch name? If we choose develop, I'd like to align the path of the manual, but if main, I don't care.

Fine with me too. Only concern i have would be that there are build scripts etc out there explicitly specifying "master"?

[itchyny]

We should avoid changing the path as much as possible, we'll have to implement redirect for the links in other websites.

[wader]

We should avoid changing the path as much as possible, we'll have to implement redirect for the links in other websites.

Good point, i was mostly concerned to not break the "default" manual /jq/manual URL in this change. So should we change /jq/manual/dev to /jq/manual/master in this PR?

[itchyny]

I don't think /master/ in the path is a good name. I was just worried about the case /dev/ for develop branch. But anyway, I think it's better to fix the manual confusion soon rather than waisting time for misalignment against the default branch name in the future. So I'm ok with merging this now. Any thoughts from other maintainers?

[wader]

Merge?

[wader]

@itchyny ok to merge?