From 30b717a4d8d102b0c02e9a3d432f49acf6580c5a Mon Sep 17 00:00:00 2001 From: xinan1911 Date: Thu, 10 Oct 2024 13:36:06 +0200 Subject: [PATCH 1/9] generate api docs --- docs/gen_ref_pages.py | 79 +++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 25 ++++++++++++-- requirements.txt | 5 +++ 3 files changed, 106 insertions(+), 3 deletions(-) create mode 100644 docs/gen_ref_pages.py diff --git a/docs/gen_ref_pages.py b/docs/gen_ref_pages.py new file mode 100644 index 000000000..fe64fcea7 --- /dev/null +++ b/docs/gen_ref_pages.py @@ -0,0 +1,79 @@ +""" +Generate the code reference pages. +Based off https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages +""" + +from pathlib import Path + +import mkdocs_gen_files + +# need to adjust to the test suite hook +#root = Path(__file__).parent.parent + +TEST_SUITE = "src/test-suite" +#src = TEST_SUITE / "eessi" +MKDOCS_SEARCH_PRIORITY = """--- +search: + boost: 0.5 +--- +""" + +# build a navigation for the menu and a dictionary of navigations for each section +#menu_nav = mkdocs_gen_files.Nav() +#navs = {} +nav = mkdocs_gen_files.Nav() + +#for path in sorted(src.rglob("*.py")): +for path in sorted(Path(f"{TEST_SUITE}/eessi/").rglob("*.py")): + module_path = path.relative_to(TEST_SUITE).with_suffix("") + doc_path = path.relative_to(TEST_SUITE).with_suffix(".md") + full_doc_path = Path("api", doc_path) + + #parts = tuple(module_path.parts) + parts = list(module_path.parts) + + #if len(parts) > 1 and tuple(parts[:-1]) not in navs: + # navs[tuple(parts[:-1])] = mkdocs_gen_files.Nav() + + if parts[-1] == "__init__": + parts = parts[:-1] + #doc_path = doc_path.with_name("index.md") + #full_doc_path = full_doc_path.with_name("index.md") + elif parts[-1] == "__main__": + continue + + # add item to menu navigation + #menu_nav[parts] = doc_path.as_posix() + nav[parts] = doc_path.as_posix() + + # walk through the parents to the item and add it to each navigation section + #for i in range(1, len(parts)): + # nav_tuple = tuple(parts[:-i]) + # doc_path_relative_to_nav = doc_path.relative_to("/".join(parts[:len(parts)-i])).as_posix() + # navs[nav_tuple][parts] = doc_path_relative_to_nav + + with mkdocs_gen_files.open(full_doc_path, "w") as fd: + #fd.write(MKDOCS_SEARCH_PRIORITY) + identifier = ".".join(parts) + #fd.write(f"::: {identifier}\n") + fd.write(f"::: {identifier}") + + mkdocs_gen_files.set_edit_path(full_doc_path, path) + + # Generate the menu navigation file +with mkdocs_gen_files.open("api/summary.md", "w") as nav_file: + #nav_file.write(MKDOCS_SEARCH_PRIORITY) + #nav_file.writelines(menu_nav.build_literate_nav()) + nav_file.writelines(nav.build_literate_nav()) + + #Generate the section navigation files, appending to any existing API content +#for key, nav in navs.items(): +# fp = '/'.join(key) +# filename = f"api/{fp}/index.md" +# +# if not Path(filename).is_file(): +# with mkdocs_gen_files.open(filename, "w") as nav_file: +# nav_file.write(MKDOCS_SEARCH_PRIORITY) + +# with mkdocs_gen_files.open(filename, "a") as nav_file: +# nav_file.writelines(nav.build_literate_nav()) diff --git a/mkdocs.yml b/mkdocs.yml index ea5a7c6c7..542149cba 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -43,7 +43,6 @@ nav: - Set up environment: using_eessi/setting_up_environment.md - Basic commands: using_eessi/basic_commands.md - Demos: using_eessi/eessi_demos.md - - EESSI in CI: using_eessi/eessi_in_ci.md - Advanced usage: - Setting up your Stratum: filesystem_layer/stratum1.md - Building software with EESSI: using_eessi/building_on_eessi.md @@ -57,6 +56,7 @@ nav: - Release notes: test-suite/release-notes.md - Known issues and workarounds: - v2023.06: known_issues/eessi-2023.06.md + - API documentation: api/ - Adding software to EESSI: - Overview: adding_software/overview.md - For contributors: @@ -74,7 +74,6 @@ nav: - Talks: talks.md # - Community meeting (Sept'22): meetings/2022-09-amsterdam.md - Contact info: contact.md - - Systems where EESSI is available: systems.md - Blog: blog/index.md plugins: - blog: @@ -96,6 +95,26 @@ plugins: contributing_sw/overview.md: adding_software/overview.md software_layer/adding_software.md: adding_software/overview.md pilot.md: repositories/pilot.md + # link to any Markdown heading + - autorefs + # api automatics documentation + - mkdocstrings: + default_handler: python + handlers: + python: + paths: [src/test-suite] + options: + docstring_style: sphinx + docstring_section_style: spacy + show_source: false + - gen-files: + scripts: + - docs/gen_ref_pages.py + - literate-nav: + nav_file: summary.md + - section-index + + markdown_extensions: # enable adding HTML attributes and CSS classes - attr_list @@ -130,7 +149,7 @@ extra: - icon: fontawesome/brands/twitter link: https://twitter.com/eessi_hpc # this gets auto-updated via update_generated_time.sh script run in update_available_software.yml action - generated_time: "Sat, 05 Oct 2024 at 01:44:07 UTC" + generated_time: "Fri, 06 Sep 2024 at 12:37:43 UTC" extra_javascript: # mermaid diagram - https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs diff --git a/requirements.txt b/requirements.txt index c4e40dd4e..9db68cf27 100644 --- a/requirements.txt +++ b/requirements.txt @@ -4,3 +4,8 @@ mkdocs-redirects mkdocs-git-revision-date-localized-plugin mkdocs-toc-sidebar-plugin mkdocs-macros-plugin +mkdocs-autorefs +mkdocstrings[python] +mkdocs-gen-files +mkdocs-literate-nav +mkdocs-section-index From 3fdb89635d1b53f27669176370a0a2afce1a1d67 Mon Sep 17 00:00:00 2001 From: Xin An <34663977+xinan1911@users.noreply.github.com> Date: Fri, 11 Oct 2024 17:18:19 +0200 Subject: [PATCH 2/9] Update deploy.yml and schedule --- .github/workflows/deploy.yml | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 38db175d5..548726b73 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -1,6 +1,9 @@ # documentation: https://help.github.com/en/articles/workflow-syntax-for-github-actions name: deploy documentation (only on push to main branch) on: + schedule: + # schedule the job to run at 12am every Saturday + cron: '0 0 * * 0' push: branches: main # Declare default permissions as read only. @@ -21,7 +24,13 @@ jobs: uses: actions/setup-python@13ae5bb136fac2878aff31522b9efb785519f984 # v4.3.0 with: python-version: '3.10' - + + - name: checkout test suite + uses: actions/checkout@v3 + with: + repository: eessi/test-suite + path: src + - name: install mkdocs + plugins run: | pip install -r requirements.txt From 80f2c3a97701e7a68f5b145733c828453b48d829 Mon Sep 17 00:00:00 2001 From: Xin An <34663977+xinan1911@users.noreply.github.com> Date: Fri, 11 Oct 2024 17:19:15 +0200 Subject: [PATCH 3/9] Update deploy.yml syntax --- .github/workflows/deploy.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 548726b73..385692fab 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -3,7 +3,7 @@ name: deploy documentation (only on push to main branch) on: schedule: # schedule the job to run at 12am every Saturday - cron: '0 0 * * 0' + - cron: '0 0 * * 0' push: branches: main # Declare default permissions as read only. From 5c7ef6521c7d2b1b55a5ddadefa834c61010537d Mon Sep 17 00:00:00 2001 From: Xin An <34663977+xinan1911@users.noreply.github.com> Date: Fri, 11 Oct 2024 17:20:56 +0200 Subject: [PATCH 4/9] Update test.yml --- .github/workflows/test.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index e8a00f85f..82a381292 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -30,6 +30,13 @@ jobs: # config: '/lint/config/changelog.yml' # args: '.' + + - name: checkout test suite + uses: actions/checkout@v3 + with: + repository: eessi/test-suite + path: src + - name: install mkdocs + plugins run: | pip install -r requirements.txt From 65131b83c41aacc847ce52bbba3dbc4bd1db8888 Mon Sep 17 00:00:00 2001 From: Xin An <34663977+xinan1911@users.noreply.github.com> Date: Mon, 14 Oct 2024 10:52:06 +0200 Subject: [PATCH 5/9] Update deploy.yml for action version --- .github/workflows/deploy.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 385692fab..c6a4227d5 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -26,7 +26,7 @@ jobs: python-version: '3.10' - name: checkout test suite - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: repository: eessi/test-suite path: src From 1994da41c6bc042abae5b544223da97061f5662b Mon Sep 17 00:00:00 2001 From: Xin An <34663977+xinan1911@users.noreply.github.com> Date: Mon, 14 Oct 2024 10:52:26 +0200 Subject: [PATCH 6/9] Update test.yml --- .github/workflows/test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 82a381292..922dcc15e 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -32,7 +32,7 @@ jobs: - name: checkout test suite - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: repository: eessi/test-suite path: src From 33762ff9c39fdd12a448714ab7ffbf85b9dd0a4a Mon Sep 17 00:00:00 2001 From: Xin An <34663977+xinan1911@users.noreply.github.com> Date: Mon, 14 Oct 2024 10:56:51 +0200 Subject: [PATCH 7/9] Update deploy.yml resolve failed build warning message: The following actions use a deprecated Node.js version and will be forced to run on node20: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8, actions/setup-python@13ae5bb136fac2878aff31522b9efb785519f984. For more info: https://github.blog/changelog/2024-03-07-github-actions-all-actions-will-run-on-node20-instead-of-node16-by-default/ --- .github/workflows/deploy.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index c6a4227d5..a9cb22453 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -16,12 +16,12 @@ jobs: contents: write steps: - name: checkout - uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 # v3.1.0 + uses: actions/checkout@v4 with: fetch-depth: 0 # need to fetch all history to ensure correct Git revision dates in docs - name: set up Python - uses: actions/setup-python@13ae5bb136fac2878aff31522b9efb785519f984 # v4.3.0 + uses: actions/setup-python@v4 with: python-version: '3.10' From 0004eb309c70344f1b2507ad91060c7c2e08fadc Mon Sep 17 00:00:00 2001 From: Xin An <34663977+xinan1911@users.noreply.github.com> Date: Mon, 14 Oct 2024 10:59:55 +0200 Subject: [PATCH 8/9] Update test.yml resolve failed build --- .github/workflows/test.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 922dcc15e..f6d1803c6 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -8,10 +8,10 @@ jobs: runs-on: ubuntu-22.04 steps: - name: checkout - uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 # v3.1.0 + uses: actions/checkout@v4 - name: set up Python - uses: actions/setup-python@13ae5bb136fac2878aff31522b9efb785519f984 # v4.3.0 + uses: actions/setup-python@v4 with: python-version: '3.10' From 12dc637665715b08d8a367ec851a98af12b6f35f Mon Sep 17 00:00:00 2001 From: Xin An <34663977+xinan1911@users.noreply.github.com> Date: Mon, 14 Oct 2024 11:09:11 +0200 Subject: [PATCH 9/9] Update test.yml actions/setup-python@v5 --- .github/workflows/test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index f6d1803c6..65d554d12 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -11,7 +11,7 @@ jobs: uses: actions/checkout@v4 - name: set up Python - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: '3.10'