github.com/artpar/rclone@v1.67.3/bin/make_backend_docs.py (about)

     1  #!/usr/bin/env python3
     2  """
     3  Make backend documentation
     4  """
     5  
     6  import sys
     7  import os
     8  import io
     9  import subprocess
    10  from pathlib import Path
    11  
    12  marker = "{{< rem autogenerated options"
    13  start = marker + " start"
    14  stop = marker + " stop"
    15  end = ">}}"
    16  
    17  def find_backends():
    18      """Return a list of all backends"""
    19      return [ x for x in os.listdir("backend") if x not in ("all",) ]
    20  
    21  def output_docs(backend, out, cwd):
    22      """Output documentation for backend options to out"""
    23      out.flush()
    24      subprocess.check_call(["./rclone", "help", "backend", backend], stdout=out)
    25  
    26  def output_backend_tool_docs(backend, out, cwd):
    27      """Output documentation for backend tool to out"""
    28      out.flush()
    29      subprocess.call(["./rclone", "backend", "help", backend], stdout=out, stderr=subprocess.DEVNULL)
    30      
    31  def alter_doc(backend):
    32      """Alter the documentation for backend"""
    33      rclone_bin_dir = Path(sys.path[0]).parent.absolute()
    34      doc_file = "docs/content/"+backend+".md"
    35      if not os.path.exists(doc_file):
    36          raise ValueError("Didn't find doc file %s" % (doc_file,))
    37      new_file = doc_file+"~new~"
    38      altered = False
    39      with open(doc_file, "r", encoding="utf_8") as in_file, open(new_file, "w", encoding="utf_8") as out_file:
    40          in_docs = False
    41          for line in in_file:
    42              if not in_docs:
    43                  if start in line:
    44                      in_docs = True
    45                      start_full = (start + "\" - DO NOT EDIT - instead edit fs.RegInfo in backend/%s/%s.go then run make backenddocs\" " + end + "\n") % (backend, backend)
    46                      out_file.write(start_full)
    47                      output_docs(backend, out_file, rclone_bin_dir)
    48                      output_backend_tool_docs(backend, out_file, rclone_bin_dir)
    49                      out_file.write(stop+" "+end+"\n")
    50                      altered = True
    51              if not in_docs:
    52                  out_file.write(line)
    53              if in_docs:
    54                  if stop in line:
    55                      in_docs = False
    56      os.rename(doc_file, doc_file+"~")
    57      os.rename(new_file, doc_file)
    58      if not altered:
    59          raise ValueError("Didn't find '%s' markers for in %s" % (start, doc_file))
    60  
    61  
    62  def main(args):
    63      # single backend
    64      if (len(args) == 2):
    65          try:
    66              alter_doc(args[1])
    67              print("Added docs for %s backend" % args[1])
    68          except Exception as e:
    69              print("Failed adding docs for %s backend: %s" % (args[1], e))
    70          return
    71  
    72      # all backends
    73      failed, success = 0, 0
    74      for backend in find_backends():
    75          try:
    76              alter_doc(backend)
    77          except Exception as e:
    78              print("Failed adding docs for %s backend: %s" % (backend, e))
    79              failed += 1
    80          else:
    81              success += 1
    82      print("Added docs for %d backends with %d failures" % (success, failed))
    83  
    84  if __name__ == "__main__":
    85      main(sys.argv)