diff --git a/documentation/images/placeholder/placeholder_circle-SMALL.png b/documentation/images/placeholder/placeholder_circle-SMALL.png new file mode 100644 index 000000000..d87e8121a Binary files /dev/null and b/documentation/images/placeholder/placeholder_circle-SMALL.png differ diff --git a/documentation/images/placeholder/placeholder_circle.png b/documentation/images/placeholder/placeholder_circle.png index d87e8121a..258267657 100644 Binary files a/documentation/images/placeholder/placeholder_circle.png and b/documentation/images/placeholder/placeholder_circle.png differ diff --git a/documentation/images/placeholder/placeholder_square-SMALL.png b/documentation/images/placeholder/placeholder_square-SMALL.png new file mode 100644 index 000000000..b51bc8fb1 Binary files /dev/null and b/documentation/images/placeholder/placeholder_square-SMALL.png differ diff --git a/documentation/images/placeholder/placeholder_square.png b/documentation/images/placeholder/placeholder_square.png index b51bc8fb1..8583725b8 100644 Binary files a/documentation/images/placeholder/placeholder_square.png and b/documentation/images/placeholder/placeholder_square.png differ diff --git a/documentation/images/placeholder/placeholder_triangle-SMALL.png b/documentation/images/placeholder/placeholder_triangle-SMALL.png new file mode 100644 index 000000000..0ee52120c Binary files /dev/null and b/documentation/images/placeholder/placeholder_triangle-SMALL.png differ diff --git a/documentation/images/placeholder/placeholder_triangle.png b/documentation/images/placeholder/placeholder_triangle.png index 0ee52120c..17d54ff2d 100644 Binary files a/documentation/images/placeholder/placeholder_triangle.png and b/documentation/images/placeholder/placeholder_triangle.png differ diff --git a/documentation/index.json b/documentation/index.json index f85750364..f81870af5 100644 --- a/documentation/index.json +++ b/documentation/index.json @@ -227,7 +227,7 @@ "description": "Supports Arm Serial Wire Debug (SWD), and acts as a UART bridge", "image": "full-sized/Debug-Probe.png", "subpath": "debug-probe.adoc" - }, + }, { "title": "MicroPython", "description": "Getting started with MicroPython", diff --git a/scripts/add_new_page.py b/scripts/add_new_page.py new file mode 100755 index 000000000..446e931e8 --- /dev/null +++ b/scripts/add_new_page.py @@ -0,0 +1,108 @@ +#!/usr/bin/env python3 + +# Example usage: +# scripts/add_new_page.py "My new HAT" +# will create documentation/asciidoc/accessories/my-new-hat.adoc and documentation/asciidoc/accessories/my-new-hat/about.adoc +# +# scripts/add_new_page.py -b new-hat "My new HAT" +# will create documentation/asciidoc/accessories/new-hat.adoc and documentation/asciidoc/accessories/new-hat/about.adoc +# +# scripts/add_new_page.py -b new-hat -s intro "My new HAT" +# will create documentation/asciidoc/accessories/new-hat.adoc and documentation/asciidoc/accessories/new-hat/intro.adoc +# +# scripts/add_new_page.py -c services "Some extra Service" +# will create documentation/asciidoc/services/some-extra-service.adoc and documentation/asciidoc/services/some-extra-service/about.adoc +# +# scripts/add_new_page.py -c services -b id -s signing_up "Raspberry Pi ID" +# will create documentation/asciidoc/services/id.adoc and documentation/asciidoc/services/id/signing_up.adoc + +import argparse +import json +import os +import random +import re +import shutil +import sys + +DOCUMENTATION_DIR = 'documentation' +INDEX_JSON = os.path.join(DOCUMENTATION_DIR, 'index.json') +IMAGES_DIR = os.path.join(DOCUMENTATION_DIR, 'images') +PLACEHOLDER_IMAGES_DIR = os.path.join(IMAGES_DIR, 'placeholder') +PLACEHOLDER_SHAPES = ('circle', 'square', 'triangle') + +if __name__ == "__main__": + parser = argparse.ArgumentParser() + parser.add_argument('name') + parser.add_argument('-c', '--category', default='accessories') + parser.add_argument('-b', '--basename') + parser.add_argument('-s', '--subfile', default='about') + args = parser.parse_args() + print(args) + + name = args.name + category = args.category + basename = args.basename + if not basename: + basename = re.sub('\W', '-', name.lower()) + subfile = f"{args.subfile}.adoc" + + # Validate the category + valid_categories = [] + with open(INDEX_JSON, 'r') as json_fh: + json_contents = json.load(json_fh) + for tab in json_contents["tabs"]: + if 'from_json' in tab: + continue + valid_categories.append(tab['path']) + if category not in valid_categories: + raise Exception(f"Invalid category {category}. Choose from {valid_categories}") + category_dir = os.path.join(DOCUMENTATION_DIR, 'asciidoc', category) + if not os.path.exists(category_dir): + raise Exception(f"{category_dir} doesn't exist") + + # Check the new page hasn't already been added + new_dir = os.path.join(category_dir, basename) + if os.path.isdir(new_dir): + raise Exception(f"{new_dir} already exists") + new_file = f"{new_dir}.adoc" + if os.path.isfile(new_file): + raise Exception(f"{new_file} already exists") + new_subfile = os.path.join(new_dir, subfile) + if os.path.isfile(new_subfile): + raise Exception(f"{new_subfile} already exists") + + print(f"Will create {new_file} and {new_subfile}") + sys.exit(0) + # Create the template AsciiDoc documentation + os.mkdir(new_dir) + with open(new_file, 'w') as fh: + fh.write(f"include::{basename}/{subfile}[]\n") + with open(new_subfile, 'w') as fh: + fh.write(f"== About\n\nAll about {name} and why it's amazing") + + # Add the placeholder images + shape = random.choice(PLACEHOLDER_SHAPES) + shutil.copyfile(os.path.join(PLACEHOLDER_IMAGES_DIR, f"placeholder_{shape}-SMALL.png"), os.path.join(IMAGES_DIR, f"{basename}-SMALL.png")) + shutil.copyfile(os.path.join(PLACEHOLDER_IMAGES_DIR, f"placeholder_{shape}.png"), os.path.join(IMAGES_DIR, 'full-sized', f"{basename}.png")) + + # And finally update the JSON which ties everything together + with open(INDEX_JSON, 'r+') as json_fh: + json_contents = json.load(json_fh) + found = False + for tab in json_contents["tabs"]: + if tab['path'] == category: + found = True + tab["subitems"].append({ + "title": name, + "description": f"Description of {name}", + "image": os.path.join('full-sized', f"{basename}.png"), + "subpath": f"{basename}.adoc", + }) + break + if not found: # this shouldn't ever happen, as we already validated the category earlier + raise Exception(f"Couldn't find tab with path {category} in {INDEX_JSON}") + json_fh.seek(0) + json.dump(json_contents, json_fh, indent=4) + + print(f"Done. Use 'git status' and 'git diff' to see what has changed, and then add more content to\n {new_subfile}") +