diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 38db175d5..a9cb22453 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. @@ -13,15 +16,21 @@ 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' - + + - name: checkout test suite + uses: actions/checkout@v4 + with: + repository: eessi/test-suite + path: src + - name: install mkdocs + plugins run: | pip install -r requirements.txt diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index e8a00f85f..65d554d12 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@v5 with: python-version: '3.10' @@ -30,6 +30,13 @@ jobs: # config: '/lint/config/changelog.yml' # args: '.' + + - name: checkout test suite + uses: actions/checkout@v4 + with: + repository: eessi/test-suite + path: src + - name: install mkdocs + plugins run: | pip install -r requirements.txt 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