diff --git a/.gitignore b/.gitignore index 4f7cd959..c497a769 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,7 @@ *.DS_Store **/__pycache__/* */index.html -_tmp_ngff_spec/ +_temp_ngff_spec/ _build _html_extra .tox diff --git a/conf.py b/conf.py index f39f70cd..9056b407 100644 --- a/conf.py +++ b/conf.py @@ -113,7 +113,11 @@ def build_served_html(clean_up=True): from pathlib import Path os.chdir(Path(__file__).parent) - + + # Keep specifications/* submodules in sync regardless of entry point + # (make, make.bat, sphinx-autobuild all import this file). + subprocess.check_call(["git", "submodule", "update", "--init", "--depth", "1"]) + # Create .htaccess to serve schemas inline (not download) os.makedirs("_html_extra", exist_ok=True) @@ -163,6 +167,14 @@ def build_served_html(clean_up=True): for version in displayed_spec_versions: # find 'pre_build.py' in 'specifications' subdirectories + # skip if submodule hasn't been checked out. + if len(os.listdir(f"specifications/{version}")) == 0: + print( + f"⚠️ No files found for version {version}. " + "This indicates missing specification files or git submodules. " + "See https://ngff.openmicroscopy.org/contributing/website for help in debugging the build." + ) + continue script = glob.glob(f"specifications/{version}/**/pre_build.py", recursive=True)[ 0 ] diff --git a/contributing/website/index.md b/contributing/website/index.md index 08b51d04..092e2916 100644 --- a/contributing/website/index.md +++ b/contributing/website/index.md @@ -6,20 +6,19 @@ Contributions to these pages are welcome as issues or PRs. To do so, create a fork of the ``ome/ngff`` repository, make your changes, and submit a pull request (PR) against the `main` branch. -## Setting up the repository -Create a fork of the ``ome/ngff`` repository. - -When cloning your fork locally, you will need to pull the submodules in `specifications/`: -```bash -git submodule init -git submodule update -``` - ## Configuration Edit [conf.py](https://github.com/ome/ngff/blob/main/conf.py) with options from the [PyData Theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/). The [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/index.html) user guide may also have more up to date instructions for configuration properties. ## Building the pages locally +Create a fork of the ``ome/ngff`` repository. +Then. clone the forked repository to your local machine. + +```bash +git clone https://github.com//ngff.git +cd ngff +``` + Before submitting changes to the ngff website, please build the pages locally and make sure that everything renders correctly. @@ -32,9 +31,18 @@ pip install specifications/dev ``` Then, you can build the pages locally with: +::::{tab-set} +:::{tab-item} Windows +```bash +.\make html +``` +::: +:::{tab-item} Linux ```bash make html ``` +::: +:::: You can then find the rendered pages under `_build/html/index.html`. Alternatively, to build and preview the pages locally: diff --git a/requirements.txt b/requirements.txt index 743590fa..18f8e8ca 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,6 +2,7 @@ bikeshed myst-parser pydata-sphinx-theme json-schema-for-humans +json-with-comments testresources sphinx-reredirects sphinxcontrib-bibtex