website: Make latest release (1.7) be default manual (#3130)

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

Makefile.am

@@ -160,10 +160,10 @@ check_DATA = tests/man.test
 # Making changes to the manpage without having the python deps means your
 # tests won't run. If you aren't making changes to the examples, you probably
 # don't care. But if you are, then you need to run the tests anyway.
-tests/man.test tests/manonig.test: $(srcdir)/docs/content/manual/manual.yml
+tests/man.test tests/manonig.test: $(srcdir)/docs/content/manual/dev/manual.yml
 if ENABLE_DOCS
 	$(AM_V_GEN) ( cd ${abs_srcdir}/docs && \
-	  $(PIPENV) run python validate_manual_schema.py content/manual/manual.yml && \
+	  $(PIPENV) run python validate_manual_schema.py content/manual/dev/manual.yml && \
 	  $(PIPENV) run python build_mantests.py )
 else
 	@echo Changes to the manual.yml require docs to be enabled to update the manual test.
@@ -176,10 +176,10 @@ endif
 # manpage, then we'll end up using the cached version. Otherwise, we need to
 # rebuild it.
 man_MANS = jq.1
-jq.1.prebuilt: $(srcdir)/docs/content/manual/manual.yml
+jq.1.prebuilt: $(srcdir)/docs/content/manual/dev/manual.yml
 if ENABLE_DOCS
 	$(AM_V_GEN) ( cd ${abs_srcdir}/docs && \
-	  $(PIPENV) run python validate_manual_schema.py content/manual/manual.yml && \
+	  $(PIPENV) run python validate_manual_schema.py content/manual/dev/manual.yml && \
 	  $(PIPENV) run python build_manpage.py ) > $@
 else
 	@echo Changes to the manual.yml require docs to be enabled to update the manpage.

docs/build_manpage.py

@@ -209,7 +209,7 @@ def dedent_body(body):
 
 def convert_manual_to_markdown():
     f = StringIO()
-    manual = load_yml_file("content/manual/manual.yml")
+    manual = load_yml_file("content/manual/dev/manual.yml")
     f.write(manual.get('manpage_intro', '\n'))
     f.write(dedent_body(manual.get('body', '\n')))
     for section in manual.get('sections', []):

docs/build_mantests.py

@@ -5,7 +5,7 @@ import re
 regex_program_pattern = re.compile(
     r'\b(?:test|match|capture|scan|split|splits|sub|gsub)\s*\(')
 
-with open('content/manual/manual.yml') as source, \
+with open('content/manual/dev/manual.yml') as source, \
         open('../tests/man.test', 'w') as man, \
         open('../tests/manonig.test', 'w') as manonig:
     manual = yaml.safe_load(source)

docs/content/manual/manual.yml

@@ -0,0 +1 @@
+v1.7/manual.yml

docs/content/manual/v1.3/manual.yml

@@ -1,11 +1,6 @@
 ---
 headline: jq 1.3 Manual
 
-history: |
-
-  *The manual for the development version of jq can be found
-  [here](../).*
-
 body: |
 
   A jq program is a "filter": it takes an input, and produces an

docs/content/manual/v1.4/manual.yml

@@ -1,11 +1,6 @@
 ---
 headline: jq 1.4 Manual
 
-history: |
-
-  *The manual for the development version of jq can be found
-  [here](../).*
-
 body: |
 
   A jq program is a "filter": it takes an input, and produces an

docs/content/manual/v1.5/manual.yml

@@ -1,11 +1,6 @@
 ---
 headline: jq 1.5 Manual
 
-history: |
-
-  *The manual for the development version of jq can be found
-  [here](../).*
-
 body: |
 
   A jq program is a "filter": it takes an input, and produces an

docs/content/manual/v1.6/manual.yml

@@ -1,11 +1,6 @@
 ---
 headline: jq 1.6 Manual
 
-history: |
-
-  *The manual for the development version of jq can be found
-  [here](../).*
-
 body: |
 
   A jq program is a "filter": it takes an input, and produces an

docs/content/manual/v1.7/manual.yml

@@ -1,11 +1,6 @@
 ---
 headline: jq 1.7 Manual
 
-history: |
-
-  *The manual for the development version of jq can be found
-  [here](../).*
-
 body: |
 
   A jq program is a "filter": it takes an input, and produces an

docs/manual_schema.yml

@@ -1,7 +1,6 @@
 type: object
 required:
   - headline
-  - history
   - body
   - manpage_intro
   - manpage_epilogue
@@ -10,8 +9,6 @@ additionalProperties: false
 properties:
   headline:
     type: string
-  history:
-    type: string
   body:
     type: string
   manpage_intro:

docs/templates/manual.html.j2

@@ -33,7 +33,17 @@
       {%- endmacro %}
       <main id="main" class="col-md-9" data-bs-spy="scroll" data-bs-target="#contents" data-bs-threshold="0,1" data-bs-root-margin="-30% 0% -70%">
         <h1>{{ headline }}</h1>
-        {{ history | markdownify }}
+        <p>
+          <em>
+            For other versions, see
+            <a href="{{ root }}/manual/v1.7/">1.7</a>,
+            <a href="{{ root }}/manual/v1.6/">1.6</a>,
+            <a href="{{ root }}/manual/v1.5/">1.5</a>,
+            <a href="{{ root }}/manual/v1.4/">1.4</a>,
+            <a href="{{ root }}/manual/v1.3/">1.3</a> or
+            <a href="{{ root }}/manual/dev/">development version</a>.
+          </em>
+        </p>
         {{ body | markdownify }}
         {%- for section in sections %}
         <section id="{{ section.title | section_id }}">{{ check_section_id(section.title | section_id) }}