{"id":27370102,"url":"https://github.com/flexcompute/autoflex","last_synced_at":"2025-04-13T08:47:59.637Z","repository":{"id":216679406,"uuid":"741932106","full_name":"flexcompute/autoflex","owner":"flexcompute","description":"A flexible, elegant API documentation extension. :books:","archived":false,"fork":false,"pushed_at":"2024-11-04T12:14:39.000Z","size":2188,"stargazers_count":0,"open_issues_count":17,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2024-11-04T12:27:28.772Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://flexcompute.github.io/autoflex/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flexcompute.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-11T12:11:27.000Z","updated_at":"2024-11-01T10:58:59.000Z","dependencies_parsed_at":"2024-08-01T00:27:10.412Z","dependency_job_id":"73e43666-4b2c-4b30-8a67-a85807131bac","html_url":"https://github.com/flexcompute/autoflex","commit_stats":null,"previous_names":["daquintero/sphinxcontrib-autoflex","flexcompute/autoflex"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flexcompute%2Fautoflex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flexcompute%2Fautoflex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flexcompute%2Fautoflex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flexcompute%2Fautoflex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flexcompute","download_url":"https://codeload.github.com/flexcompute/autoflex/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248688176,"owners_count":21145762,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-13T08:47:58.664Z","updated_at":"2025-04-13T08:47:59.624Z","avatar_url":"https://github.com/flexcompute.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `autoflex` Sphinx Documentation Extension\n\nA flexible, nicer way of generating API docs without requiring custom docstrings.\n\n## Overview\n\nOne of the main complexities we have is that managing `rst` code blocks in docstrings is complicated. It involves manually writing and updating parameter descriptions rather than focusing on the actual docstrings.\n\nWhen we have multiple classes, and multiple inherited classes, it is hard to keep track of each code block and all the added parameters. For example, it would be possible to manually input parameters at each particular stage. However, it would be nice if this could be extracted directly out of each class declaration automatically and render it in a nice way.\n\nThis extension aims to do that.\n\n### Objectives\n\n- Improve the API template for `autodoc` which can be limited.\n- For each class, such as `tidy3d` complex classes, properly generate a nicer template of the parameters and methods that extends how autodoc works.\n- Generate an index of each API directive that can be easily searched by corresponding themes like the `sphinx_book_theme`.\n- For inherited classes, have the option to easily define the methods and parameters that we want to generate documentation for.\n- Have the option to generate custom HTML relevant to each class in a way defined by the class docstring.\n- Make sure the docstrings don't interfere with help messages such as ipython, etc. (Maybe explore how to compile relevant docstrings into the help messages).\n\n**API Docstrings Improvements**\n\nWhen we have highly complex classes that have multiple inherited parameters, it is desired to have a clear definition of each specific class and its parameters, types and defaults. Whilst this can be done manually for an individual class or method, as a project increases in complexity, it is desired to understand the relevant docstrings for each class and method.\n\n## Usage\n\nThe idea is that we can use the `autoflex` directive to improve the data structure generated during the `autosummary` process instead of the `automodule` or `autoclass` directive.\n\nInstall the package in `development` mode:\n```bash\npoetry install -E dev\n```\n\nBuild the local basic documentation with the extension linked:\n\n```bash\npoetry run python -m sphinx docs/ _docs/\n```\n\nBasic Example:\n\n```rst\n.. autoflex:: somepackage.BasicClass # CURRENTLY NOT WORKING\n```\n\n## Links\n\n-   Source: \u003chttps://github.com/sphinx-contrib/sphinxcontrib-autoflex /\u003e\n-   Bugs: \u003chttps://github.com/sphinx-contrib/sphinxcontrib-autoflex/issues /\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflexcompute%2Fautoflex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflexcompute%2Fautoflex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflexcompute%2Fautoflex/lists"}