{"id":15893714,"url":"https://github.com/ziselsberger/use_doc_to_readme","last_synced_at":"2025-04-02T18:15:53.014Z","repository":{"id":153525951,"uuid":"629687763","full_name":"ziselsberger/use_doc_to_readme","owner":"ziselsberger","description":"How to use doc_to_readme in another repository","archived":false,"fork":false,"pushed_at":"2024-12-14T15:57:09.000Z","size":93,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-08T08:47:10.491Z","etag":null,"topics":["documentation","python","readme"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ziselsberger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2023-04-18T20:30:48.000Z","updated_at":"2024-12-14T15:57:12.000Z","dependencies_parsed_at":"2024-10-28T03:24:35.548Z","dependency_job_id":"db22f1c0-ea7f-4bf9-95f9-794e85833a48","html_url":"https://github.com/ziselsberger/use_doc_to_readme","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ziselsberger%2Fuse_doc_to_readme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ziselsberger%2Fuse_doc_to_readme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ziselsberger%2Fuse_doc_to_readme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ziselsberger%2Fuse_doc_to_readme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ziselsberger","download_url":"https://codeload.github.com/ziselsberger/use_doc_to_readme/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246866100,"owners_count":20846496,"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":["documentation","python","readme"],"created_at":"2024-10-06T08:12:55.309Z","updated_at":"2025-04-02T18:15:52.996Z","avatar_url":"https://github.com/ziselsberger.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# _doc_to_readme_ - Automated Module Documentation\n\n### Step-by-step intro on how to integrate [doc_to_readme](https://github.com/ziselsberger/doc_to_readme) in your repository\n\n* [GitHub](#github)\n* [GitLab](#gitlab)\n* [Bitbucket](#bitbucket)\n* [Azure DevOps](#azure-devops)\n\n## GitHub\n\n#### 1. Add dir `.github/workflows`\n\n#### 2. Use this [GitHub Actions Workflow File (.yml)](.github/workflows/update_readme.yml)\n\n```yaml\nname: Update README.md\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  update-docu:\n    permissions:\n      contents: write\n    uses: ziselsberger/doc_to_readme/.github/workflows/update_readme_github.yml@main\n    with:\n      PATH_TO_README: \"README.md\"\n      ROOT_DIR: \"\"\n      EXCLUDED_MODULES: \"doc_to_md\"\n      SELECTED_MODULES: \"\"\n      SEPARATED: \"true\"\n```\n\n#### 3. Update branch name and variables (if needed)\n\n* Branch name defaults to **main**\n* These _**variables**_ are passed to the [reusable workflow](https://github.com/ziselsberger/doc_to_readme/blob/main/.github/workflows/update_readme_github.yml) as _**inputs**_ for [doc_to_md.py](https://github.com/ziselsberger/doc_to_readme/blob/main/src/doc_to_md.py).: \n  * `PATH_TO_README` \n  * `ROOT_DIR`\n  * `EXCLUDED_MODULES` \n  * `SELECTED_MODULES` \n  * `SEPARATED`\n\n```yaml\ninputs:\n  PATH_TO_README:\n    required: false\n    default: \"README.md\"\n    type: string\n  ROOT_DIR:\n    required: fales\n    type: string     # directory used as root for searching modules, defaults to folder containing README.md\n  EXCLUDED_MODULES:\n    required: false\n    type: string     # provide module name(s) (without '.py'), separated with a whitespace, e.g. \"module_x module_y\"\n  SELECTED_MODULES:\n    required: false\n    type: string     # same as excluded modules\n  SEPARATED:\n    required: false\n    default: \"true\"  # create one table per module\n    type: string\n```\n\n\n\u003e[!TIP]\n\u003e #### More information about reusable workflows:  \n\u003e https://dev.to/n3wt0n/avoid-duplication-github-actions-reusable-workflows-3ae8  \n\u003e https://docs.github.com/en/actions/using-workflows/reusing-workflows#creating-a-reusable-workflow\n\n## GitLab\n#### 1. Have a look at these [Instructions](https://github.com/ziselsberger/doc_to_readme/blob/main/How_to_setup_the_pipelines.md#gitlab) on how to:\n* set up a **Project Access Token** \n* add the token to the **CI Variables**\n\n#### 2. Use this [GitLab CI File (.yml)](.gitlab-ci.yml)\n\nThe environment variables of the external pipeline file can be overwritten in .gitlab-ci.yml file:\n\n```yaml\nvariables:\n  PATH_TO_README: \"README.md\"\n  ROOT_DIR: \"\"\n  EXCLUDED_MODULES: \"doc_to_md\"\n  SELECTED_MODULES: \"\"\n  SEPARATED: \"true\"\n```\n\nuse `include` / `include:remote` --\u003e Pipeline YAML file stored in GitHub  \n\n```yaml\ninclude: \"https://github.com/ziselsberger/doc_to_readme/raw/main/templates/.update_readme_gitlab.yml\"\n```\n\n\u003e [!IMPORTANT]\n\u003e It must be the URL to the **raw** YAML file, otherwise the pipeline will fail!  \n\u003e Error Message: _Included file `https://../.update_readme_gitlab.yml` does not have valid YAML syntax!_\n\n\u003e[!TIP]\n\u003e #### GitLab Documentation:   \n\u003e * https://docs.gitlab.com/ee/ci/yaml/includes.html  \n\u003e * https://docs.gitlab.cn/14.0/ee/ci/yaml/includes.html#overriding-external-template-values  \n\n\n## Bitbucket\n\n#### 1. Have a look at these [Instructions](https://github.com/ziselsberger/doc_to_readme/blob/main/How_to_setup_the_pipelines.md#bitbucket) on how to:\n* enable pipelines \n\n#### 2. Use this [Bitbucket Pipelines File](bitbucket-pipelines.yml)\n\n* If you already have bitbucket-pipelines.yml: Copy the `definition` and add the step `*doc_to_readme` in your existing pipeline.\n\n```yaml\ndefinitions:\n  steps:\n    - step: \u0026doc_to_readme\n        name: Add module documentation to README\n        image: alpine:latest\n        script:\n          - apk add --no-cache python3 bash git\n          - git fetch\n          - git clone 'https://github.com/ziselsberger/doc_to_readme.git'\n          - cp ./doc_to_readme/src/doc_to_md/doc_to_md.py .\n          - rm -rf doc_to_readme\n          - python3 doc_to_md.py -f README.md [-r ROOT_DIR] [-e EXCLUDED_MODULES] [-m SELECTED_MODULES] [--separated]\n          - rm doc_to_md.py\n          - lines=$(git status -s | wc -l)\n          - |\n            if [ $lines -gt 0 ];then\n              git add \"README.md\"\n              git commit -m \"Auto-update README.md [skip ci]\"\n              git push\n            fi\n            \npipelines:\n  branches:\n    main:\n      - step: *doc_to_readme\n```\n\n#### 3. Check \u0026 update (if needed)\n\n* BRANCH_NAME (default is **main**):  \n  ```yaml\n  pipelines:\n    branches:\n      BRANCH_NAME:\n        ... \n  ```\n  \n* PATH_TO_README\n  ```yaml\n  # .push:\n  git add PATH_TO_README   \n  \n  # script:\n  python3 doc_to_md.py -f PATH_TO_README  \n  ```\n  \n* Call `doc_to_md.py` with optional arguments (-r / -e / -m / --separated)  \n  ```shell\n  -r ROOT_DIR          # Directory used as root for searching modules, defaults to folder containing README.md\n  -e EXCLUDED_MODULES  # excluded module name(s) (without '.py'), separated with a whitespace, e.g. \"module_x module_y\"\n  -m SELECTED_MODULES  # selected module(s)\n  --separted           # create one table per module\n  ```\n\n\u003e[!NOTE]\n\u003e **Currently, it's not possible to use pipeline yml files from other repositories.**  \n\u003e Status on ongoing development: https://jira.atlassian.com/browse/BCLOUD-14078\n\n## Azure DevOps\n\n#### 1. Use this [Azure DevOps CI File](azure-pipelines.yaml)\n\n#### 2. Check \u0026 update (if needed)\n  \n* Variable `PATH_TO_README`\n  ```yaml\n  variables:\n    PATH_TO_README: README.md\n  ```\n  \n* Call `doc_to_md.py` with optional arguments (-r / -e / -m / --separated)  \n  ```shell\n  python doc_to_md.py -f $(PATH_TO_README) [-r ROOT_DIR] [-e EXCLUDED_MODULES] [-m SELECTED_MODULES] [--separated]\n  \n  -r ROOT_DIR          # Directory used as root for searching modules, defaults to folder containing README.md\n  -e EXCLUDED_MODULES  # excluded module name(s) (without '.py'), separated with a whitespace, e.g. \"module_x module_y\"\n  -m SELECTED_MODULES  # selected module(s)\n  --separted           # create one table per module\n  ```\n\n## Functions \u0026 Classes  \n\n### [main.py](./main.py)\n\n| Type | Name/Call | Description |\n| --- | --- | --- |\n| function  | \u003cpre lang='py'\u003ehello_world()\u003c/pre\u003e | Just says hello |\n\n### [my_classes.py](./src/my_classes.py)\n\n| Type | Name/Call | Description |\n| --- | --- | --- |\n| class  | \u003cpre lang='py'\u003eTechnicalQualityTests\u003c/pre\u003e | Base class for all technical QC Tests. |\n| method (TechnicalQualityTests) | \u003cpre lang='py'\u003eadd_to_dict(\u0026#13;      self, \u0026#13;      test_name: str, \u0026#13;      test_result: Tuple[bool, str]\u0026#13;  ) -\u003e None\u003c/pre\u003e | Add QC result to dictionary. |\n\n### [my_functions.py](./src/my_functions.py)\n\n| Type | Name/Call | Description |\n| --- | --- | --- |\n| function  | \u003cpre lang='py'\u003emean(x: int = 1, y: int = 2) -\u003e float\u003c/pre\u003e | Calculate mean of x and y. |\n| function  | \u003cpre lang='py'\u003eadd(x: int = 4, y: int = 5) -\u003e int\u003c/pre\u003e | Add two numbers (x and y). |\n| function  | \u003cpre lang='py'\u003emultiply(x: int = 6, y: int = 7) -\u003e int\u003c/pre\u003e | Multiply two numbers (x and y). |\n\nCreated with: [doc_to_readme](https://github.com/ziselsberger/doc_to_readme)  \n[MIT](https://github.com/ziselsberger/doc_to_readme/blob/main/LICENSE) \u0026copy; 2023 Mirjam Ziselsberger\n\n---\n**Last Update:** 2024-12-14","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fziselsberger%2Fuse_doc_to_readme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fziselsberger%2Fuse_doc_to_readme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fziselsberger%2Fuse_doc_to_readme/lists"}