Step-by-step intro on how to integrate doc_to_readme in your repository
2. Use this GitHub Actions Workflow File (.yml)
name: Update README.md
on:
push:
branches:
- main
jobs:
update-docu:
permissions:
contents: write
uses: ziselsberger/doc_to_readme/.github/workflows/update_readme_github.yml@main
with:
PATH_TO_README: "README.md"
ROOT_DIR: ""
EXCLUDED_MODULES: "doc_to_md"
SELECTED_MODULES: ""
SEPARATED: "true"
- Branch name defaults to main
- These variables are passed to the reusable workflow as inputs for doc_to_md.py.:
PATH_TO_README
ROOT_DIR
EXCLUDED_MODULES
SELECTED_MODULES
SEPARATED
inputs:
PATH_TO_README:
required: false
default: "README.md"
type: string
ROOT_DIR:
required: fales
type: string # directory used as root for searching modules, defaults to folder containing README.md
EXCLUDED_MODULES:
required: false
type: string # provide module name(s) (without '.py'), separated with a whitespace, e.g. "module_x module_y"
SELECTED_MODULES:
required: false
type: string # same as excluded modules
SEPARATED:
required: false
default: "true" # create one table per module
type: string
https://dev.to/n3wt0n/avoid-duplication-github-actions-reusable-workflows-3ae8
https://docs.github.com/en/actions/using-workflows/reusing-workflows#creating-a-reusable-workflow
1. Have a look at these Instructions on how to:
- set up a Project Access Token
- add the token to the CI Variables
2. Use this GitLab CI File (.yml)
The environment variables of the external pipeline file can be overwritten in .gitlab-ci.yml file:
variables:
PATH_TO_README: "README.md"
ROOT_DIR: ""
EXCLUDED_MODULES: "doc_to_md"
SELECTED_MODULES: ""
SEPARATED: "true"
There are two options, how to include the external pipeline:
a) use include
/ include:remote
--> Pipeline YAML file stored in GitHub
include: "https://github.com/ziselsberger/doc_to_readme/raw/main/templates/.update_readme_gitlab.yml"
It must be the URL to the raw YAML file, otherwise the pipeline will fail!
Error Message: Included filehttps://../.update_readme_gitlab.yml
does not have valid YAML syntax!
b) use include:project
--> only possible if you have access to this GitLab project
include:
project: 'csat6025/doc_to_readme'
file: '/templates/.update_readme_gitlab.yml'
1. Have a look at these Instructions on how to:
- enable pipelines
2. Use this Bitbucket Pipelines File
- If you already have bitbucket-pipelines.yml: Copy the
definition
and add the step*doc_to_readme
in your existing pipeline(s).
definitions:
steps:
- step: &doc_to_readme
name: Add module documentation to README
image: alpine:latest
script:
- apk add --no-cache python3 bash git
- git fetch
- git clone 'https://github.com/ziselsberger/doc_to_readme.git'
- cp ./doc_to_readme/src/doc_to_md/doc_to_md.py .
- rm -rf doc_to_readme
- python3 doc_to_md.py -f README.md [-r ROOT_DIR] [-e EXCLUDED_MODULES] [-m SELECTED_MODULES] [--separated]
- rm doc_to_md.py
- lines=$(git status -s | wc -l)
- |
if [ $lines -gt 0 ];then
git add "README.md"
git commit -m "Auto-update README.md [skip ci]"
git push
fi
pipelines:
branches:
main:
- step: *doc_to_readme
-
BRANCH_NAME (default is main):
pipelines: branches: BRANCH_NAME: ...
-
PATH_TO_README
# .push: git add PATH_TO_README # script: python3 doc_to_md.py -f PATH_TO_README
-
Call
doc_to_md.py
with optional arguments (-r / -e / -m / --separated)-r ROOT_DIR # Directory used as root for searching modules, defaults to folder containing README.md -e EXCLUDED_MODULES # excluded module name(s) (without '.py'), separated with a whitespace, e.g. "module_x module_y" -m SELECTED_MODULES # selected module(s) --separted # create one table per module
Currently, it's not possible to use pipeline yml files from other repositories.
Status on ongoing development: https://jira.atlassian.com/browse/BCLOUD-14078
Type | Name/Call | Description |
---|---|---|
function | hello_world() |
Just says hello |
Type | Name/Call | Description |
---|---|---|
class | TechnicalQualityTests |
Base class for all technical QC Tests. |
method (TechnicalQualityTests) | add_to_dict(self, test_name: str, test_result: Tuple[bool, str]) -> None |
Add QC result to dictionary. |
Type | Name/Call | Description |
---|---|---|
function | mean(x: int = 1, y: int = 2) -> float |
Calculate mean of x and y. |
function | add(x: int = 4, y: int = 5) -> int |
Add two numbers (x and y). |
function | multiply(x: int = 6, y: int = 7) -> int |
Multiply two numbers (x and y). |
Created with: doc_to_readme
MIT © 2023 Mirjam Ziselsberger
Last Update: 2023-04-29