Skip to content

Commit 0f3aa17

Browse files
albertonyalbertony
committed
build: improve backend docs autogenerated marker line
Replace custom rem hugo shortcode template with HTML comment. HTML comments are now allowed in Hugo without enabling unsafe HTML parsing. Improve the text in the comment: Remove unnecessary quoting, and avoid impression that make backenddocs has to be run and results committed, since we have a lint check which will then report error because we want to prevent manual changes in autogenerated sections. Disable the markdownlint rule line-length on the autogenerated marker line. Make the autogenerated marker detection a bit more robust. See #8942 for more details.
1 parent 8f74e7d commit 0f3aa17

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

72 files changed

+152
-149
lines changed

‎bin/check_autogenerated_edits.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,9 +51,9 @@ def find_regions(lines):
5151
regions = []
5252
start = None
5353
for i, line in enumerate(lines, 1):
54-
if "rem autogenerated options start" in line:
54+
if line.lstrip().startswith("<!-- autogenerated options start "):
5555
start = i
56-
elif "rem autogenerated options stop" in line and start is not None:
56+
elif start is not None and line.rstrip().endswith(" autogenerated options stop -->"):
5757
regions.append((start, i))
5858
start = None
5959
return regions

‎bin/make_backend_docs.py‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,12 @@
99
import subprocess
1010
from pathlib import Path
1111

12-
marker = "{{< rem autogenerated options"
13-
start = marker + " start"
14-
stop = marker + " stop"
15-
end = ">}}"
12+
begin = "<!-- "
13+
end = " -->"
14+
marker = "autogenerated options"
15+
line_marker_start_prefix = begin + marker + " start "
16+
line_marker_stop = begin + marker + " stop" + end
17+
markdownlint_disable = begin + "markdownlint-disable-line line-length" + end
1618

1719
def find_backends():
1820
"""Return a list of all backends"""
@@ -27,7 +29,7 @@ def output_backend_tool_docs(backend, out, cwd):
2729
"""Output documentation for backend tool to out"""
2830
out.flush()
2931
subprocess.call(["./rclone", "--config=/notfound", "backend", "help", backend], stdout=out, stderr=subprocess.DEVNULL)
30-
32+
3133
def alter_doc(backend):
3234
"""Alter the documentation for backend"""
3335
rclone_bin_dir = Path(sys.path[0]).parent.absolute()
@@ -43,23 +45,23 @@ def alter_doc(backend):
4345
in_docs = False
4446
for line in in_file:
4547
if not in_docs:
46-
if start in line:
48+
if line.lstrip().startswith(line_marker_start_prefix):
4749
in_docs = True
48-
start_full = (start + "\" - DO NOT EDIT - instead edit fs.RegInfo in backend/%s/%s.go then run make backenddocs\" " + end + "\n") % (backend, backend)
49-
out_file.write(start_full)
50+
line_marker_start = (line_marker_start_prefix + "- DO NOT EDIT - instead edit fs.RegInfo in backend/%s/%s.go and run make backenddocs to verify" + end) % (backend, backend)
51+
out_file.write(line_marker_start + " " + markdownlint_disable + "\n")
5052
output_docs(backend, out_file, rclone_bin_dir)
5153
output_backend_tool_docs(backend, out_file, rclone_bin_dir)
52-
out_file.write(stop+" "+end+"\n")
54+
out_file.write(line_marker_stop + "\n")
5355
altered = True
5456
if not in_docs:
5557
out_file.write(line)
5658
if in_docs:
57-
if stop in line:
59+
if line.strip() == line_marker_stop:
5860
in_docs = False
5961
os.rename(doc_file, doc_file+"~")
6062
os.rename(new_file, doc_file)
6163
if not altered:
62-
raise ValueError("Didn't find '%s' markers for in %s" % (start, doc_file))
64+
raise ValueError("Didn't find '%s' markers in %s" % (line_marker_start_prefix, doc_file))
6365

6466

6567
def main(args):

‎bin/make_manual.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,7 @@ def read_doc(doc):
152152
# Make [...](/links/) absolute
153153
contents = re.sub(r'\]\((\/.*?\/(#.*)?)\)', r"](https://rclone.org\1)", contents)
154154
# Add additional links on the front page
155-
contents = re.sub(r'\{\{< rem MAINPAGELINK >\}\}', "- [Donate.](https://rclone.org/donate/)", contents)
155+
contents = re.sub(r'<!-- MAINPAGELINK -->', "- [Donate.](https://rclone.org/donate/)", contents)
156156
# Interpret provider shortcode
157157
# {{< provider name="Amazon S3" home="https://aws.amazon.com/s3/" config="/s3/" >}}
158158
contents = re.sub(r'\{\{<\s*provider.*?name="(.*?)".*?>\}\}', r"- \1", contents)

‎bin/make_rc_docs.sh‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ fusermount -u -z /tmp/rclone/rc_mount > /dev/null 2>&1 || umount /tmp/rclone/rc_
1515

1616
awk '
1717
BEGIN {p=1}
18-
/^\{\{< rem autogenerated start/ {print;system("cat /tmp/rclone/z.md");p=0}
19-
/^\{\{< rem autogenerated stop/ {p=1}
18+
/^<!-- autogenerated start/ {print;system("cat /tmp/rclone/z.md");p=0}
19+
/^<!-- autogenerated stop/ {p=1}
2020
p' docs/content/rc.md > /tmp/rclone/rc.md
2121

2222
mv /tmp/rclone/rc.md docs/content/rc.md

‎docs/content/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ notoc: true
1515
- [What providers does rclone support?](#providers)
1616
- [Download](/downloads/)
1717
- [Install](/install/)
18-
{{< rem MAINPAGELINK >}}
18+
<!-- MAINPAGELINK -->
1919

2020
## About rclone {#about}
2121

‎docs/content/alias.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ Copy another local directory to the alias directory called source
104104
rclone copy /home/source remote:source
105105
```
106106

107-
{{< rem autogenerated options start" - DO NOT EDIT - instead edit fs.RegInfo in backend/alias/alias.go then run make backenddocs" >}}
107+
<!-- autogenerated options start - DO NOT EDIT - instead edit fs.RegInfo in backend/alias/alias.go and run make backenddocs to verify --> <!-- markdownlint-disable-line line-length -->
108108
### Standard options
109109

110110
Here are the Standard options specific to alias (Alias for an existing remote).
@@ -137,4 +137,4 @@ Properties:
137137
- Type: string
138138
- Required: false
139139

140-
{{< rem autogenerated options stop >}}
140+
<!-- autogenerated options stop -->

‎docs/content/archive.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -236,7 +236,8 @@ It would be possible to add ISO support fairly easily as the library we use ([go
236236

237237
It would be possible to add write support, but this would only be for creating new archives, not for updating existing archives.
238238

239-
{{< rem autogenerated options start" - DO NOT EDIT - instead edit fs.RegInfo in backend/archive/archive.go then run make backenddocs" >}}
239+
<!-- autogenerated options start - DO NOT EDIT - instead edit fs.RegInfo in backend/archive/archive.go and run make backenddocs to verify --> <!-- markdownlint-disable-line line-length -->
240+
240241
### Standard options
241242

242243
Here are the Standard options specific to archive (Read archives).
@@ -283,4 +284,4 @@ Any metadata supported by the underlying remote is read and written.
283284

284285
See the [metadata](/docs/#metadata) docs for more info.
285286

286-
{{< rem autogenerated options stop >}}
287+
<!-- autogenerated options stop -->

‎docs/content/authors.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,9 @@ description: "Rclone Authors and Contributors"
1212

1313
## Contributors
1414

15-
{{< rem `email addresses removed from here need to be added to
15+
<!-- email addresses removed from here need to be added to
1616
bin/.ignore-emails to make sure update-authors.py doesn't immediately
17-
put them back in again.` >}}
17+
put them back in again. -->
1818

1919
- Alex Couper <amcouper@gmail.com>
2020
- Leonid Shalupov <leonid@shalupov.com> <shalupov@diverse.org.ru>

‎docs/content/azureblob.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -368,7 +368,7 @@ If you want to access resources with public anonymous access then set
368368
rclone lsf :azureblob,account=ACCOUNT:CONTAINER
369369
```
370370

371-
{{< rem autogenerated options start" - DO NOT EDIT - instead edit fs.RegInfo in backend/azureblob/azureblob.go then run make backenddocs" >}}
371+
<!-- autogenerated options start - DO NOT EDIT - instead edit fs.RegInfo in backend/azureblob/azureblob.go and run make backenddocs to verify --> <!-- markdownlint-disable-line line-length -->
372372
### Standard options
373373

374374
Here are the Standard options specific to azureblob (Microsoft Azure Blob Storage).
@@ -1040,7 +1040,7 @@ Properties:
10401040
- Type: string
10411041
- Required: false
10421042

1043-
{{< rem autogenerated options stop >}}
1043+
<!-- autogenerated options stop -->
10441044

10451045
### Custom upload headers
10461046

‎docs/content/azurefiles.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -348,7 +348,7 @@ Setting this can be useful if you wish to use the `az` CLI on a host with
348348
a System Managed Identity that you do not want to use.
349349
Don't set `env_auth` at the same time.
350350

351-
{{< rem autogenerated options start" - DO NOT EDIT - instead edit fs.RegInfo in backend/azurefiles/azurefiles.go then run make backenddocs" >}}
351+
<!-- autogenerated options start - DO NOT EDIT - instead edit fs.RegInfo in backend/azurefiles/azurefiles.go and run make backenddocs to verify --> <!-- markdownlint-disable-line line-length -->
352352
### Standard options
353353

354354
Here are the Standard options specific to azurefiles (Microsoft Azure Files).
@@ -793,7 +793,7 @@ Properties:
793793
- Type: string
794794
- Required: false
795795

796-
{{< rem autogenerated options stop >}}
796+
<!-- autogenerated options stop -->
797797

798798
### Custom upload headers
799799

0 commit comments

Comments
 (0)