From ede1ca6414ed2f79dd712746b27d22ece667e901 Mon Sep 17 00:00:00 2001 From: very-doge-wow <95224950+very-doge-wow@users.noreply.github.com> Date: Tue, 28 May 2024 16:53:10 +0200 Subject: [PATCH] feat: introduce advanced-html (#94) * feat: introduce advanced-html * docs: md lint * test: add test for advanced html * docs: fix * cicd: add action for github pages --------- Co-authored-by: fabianfgross --- .github/workflows/github-pages.yml | 34 ++ EXAMPLE/prometheus-advanced.html | 610 +++++++++++++++++++++++++++++ README.md | 10 +- stella.py | 5 +- writer/doc_writer.py | 232 ++++++++++- writer/doc_writer_test.py | 287 +++++++++++++- 6 files changed, 1159 insertions(+), 19 deletions(-) create mode 100644 .github/workflows/github-pages.yml create mode 100644 EXAMPLE/prometheus-advanced.html diff --git a/.github/workflows/github-pages.yml b/.github/workflows/github-pages.yml new file mode 100644 index 0000000..68f4ac8 --- /dev/null +++ b/.github/workflows/github-pages.yml @@ -0,0 +1,34 @@ +name: Deploy Example to GitHub Pages + +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.12' + + - name: Install Pipenv + run: pip install pipenv + + - name: Install dependencies + run: pipenv install + + - name: Run Python script + run: pipenv run python stella.py -fh -ah -hcp EXAMPLE/prometheus -o ./index.html + + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./ diff --git a/EXAMPLE/prometheus-advanced.html b/EXAMPLE/prometheus-advanced.html new file mode 100644 index 0000000..27c3b06 --- /dev/null +++ b/EXAMPLE/prometheus-advanced.html @@ -0,0 +1,610 @@ + + + + + + pipeship-application + + + + +
+
+

prometheus

+

Version: 25.18.0 Version: v2.51.0 Version: v2 Type: application

+

Description

+

Prometheus is a monitoring system and time series database.

+

Dependencies

+

This chart depends on the following subcharts.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameVersionRepositoryCondition
alertmanager1.10.*https://prometheus-community.github.io/helm-chartsalertmanager.enabled
kube-state-metrics5.17.*https://prometheus-community.github.io/helm-chartskube-state-metrics.enabled
prometheus-node-exporter4.31.*https://prometheus-community.github.io/helm-chartsprometheus-node-exporter.enabled
prometheus-pushgateway2.8.*https://prometheus-community.github.io/helm-chartsprometheus-pushgateway.enabled
+

Templates

+

The following templates will be deployed.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Path
vpa.yaml
pdb.yaml
ingress.yaml
deploy.yaml
network-policy.yaml
service.yaml
clusterrole.yaml
sts.yaml
cm.yaml
pvc.yaml
serviceaccount.yaml
psp.yaml
headless-svc.yaml
extra-manifests.yaml
clusterrolebinding.yaml
rolebinding.yaml
+

Objects

+

The aforementioned templates will deploy the following objects.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
KindFrom template
VerticalPodAutoscalervpa.yaml
PodDisruptionBudgetpdb.yaml
Ingressingress.yaml
Deploymentdeploy.yaml
NetworkPolicynetwork-policy.yaml
Serviceservice.yaml
ClusterRoleclusterrole.yaml
StatefulSetsts.yaml
ConfigMapcm.yaml
PersistentVolumeClaimpvc.yaml
ServiceAccountserviceaccount.yaml
PodSecurityPolicypsp.yaml
Serviceheadless-svc.yaml
ClusterRoleBindingclusterrolebinding.yaml
RoleBindingrolebinding.yaml
+

Values

+

The following values can/will be used for deployments.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionDefaultExample
alertRelabelConfigs
alertRelabelConfigs: {}
alertmanager
alertmanager:
  enabled: true
  persistence:
    size: 2Gi
  podSecurityContext:
    fsGroup: 65534
    runAsGroup: 65534
    runAsNonRoot: true
    runAsUser: 65534
commonMetaLabelsAdditional labels to attach to all resources
commonMetaLabels: {}
configmapReloadMonitors ConfigMap changes and POSTs to a URL. Ref: https://github.com/prometheus-operator/prometheus-operator/tree/main/cmd/prometheus-config-reloader
Expand
configmapReload:
  env: []
  prometheus:
    containerSecurityContext: {}
    enabled: true
    extraArgs: {}
    extraConfigmapMounts: []
    extraVolumeDirs: []
    extraVolumeMounts: []
    image:
      digest: ''
      pullPolicy: IfNotPresent
      repository: quay.io/prometheus-operator/prometheus-config-reloader
      tag: v0.72.0
    name: configmap-reload
    resources: {}
  reloadUrl: ''
configmapReload.envenv sets environment variables to pass to the container. Can be set as name/value pairs, read from secrets or configmaps.
configmapReload:
  env: []
Expand
env:
  - name: SOMEVAR
    value: somevalue
  - name: SOMEVARAGAIN
    value: somevalueanother
  - name: strawberry
    value: redanddelishous
  - name: melon
    value: greenandred
  - name: justanother
    value: dayinparadise
  - name: PASSWORD
    valueFrom:
      secretKeyRef:
        name: mysecret
        key: password
        optional: false
configmapReload.prometheusDefine values for the prometheus configuration.
Expand
configmapReload:
  prometheus:
    containerSecurityContext: {}
    enabled: true
    extraArgs: {}
    extraConfigmapMounts: []
    extraVolumeDirs: []
    extraVolumeMounts: []
    image:
      digest: ''
      pullPolicy: IfNotPresent
      repository: quay.io/prometheus-operator/prometheus-config-reloader
      tag: v0.72.0
    name: configmap-reload
    resources: {}
configmapReload.prometheus.containerSecurityContextSecurity context to be added to configmap-reload container
configmapReload:
  prometheus:
    containerSecurityContext: {}
configmapReload.prometheus.enabledIf false, the configmap-reload container will not be deployed.
configmapReload:
  prometheus:
    enabled: true
configmapReload.prometheus.extraArgsAdditional configmap-reload container arguments
configmapReload:
  prometheus:
    extraArgs: {}
configmapReload.prometheus.extraConfigmapMountsAdditional configmap-reload mounts.
configmapReload:
  prometheus:
    extraConfigmapMounts: []
extraConfigmapMounts:
  - name: prometheus-alerts
    mountPath: /etc/alerts.d
    subPath: ""
    configMap: prometheus-alerts
    readOnly: true
configmapReload.prometheus.extraVolumeDirsAdditional configmap-reload volume directories
configmapReload:
  prometheus:
    extraVolumeDirs: []
configmapReload.prometheus.extraVolumeMountsAdditional configmap-reload volume mounts
configmapReload:
  prometheus:
    extraVolumeMounts: []
configmapReload.prometheus.imageconfigmap-reload container image
configmapReload:
  prometheus:
    image:
      digest: ''
      pullPolicy: IfNotPresent
      repository: quay.io/prometheus-operator/prometheus-config-reloader
      tag: v0.72.0
configmapReload.prometheus.image.digestWhen digest is set to a non-empty value, images will be pulled by digest (regardless of tag value).
configmapReload:
  prometheus:
    image:
      digest: ''
configmapReload.prometheus.nameconfigmap-reload container name
configmapReload:
  prometheus:
    name: configmap-reload
configmapReload.prometheus.resourcesconfigmap-reload resource requests and limits. Ref: http://kubernetes.io/docs/user-guide/compute-resources/
configmapReload:
  prometheus:
    resources: {}
configmapReload.reloadUrlURL for configmap-reload to use for reloads
configmapReload:
  reloadUrl: ''
extraManifests
extraManifests: []
extraScrapeConfigs
extraScrapeConfigs: ''
forceNamespace
forceNamespace: ''
imagePullSecretsDefine ImagePullSecrets for the deployment.
imagePullSecrets: []
kube-state-metrics
kube-state-metrics:
  enabled: true
networkPolicy
networkPolicy:
  enabled: false
podSecurityPolicyDefine whether to enable the pod security policy.
podSecurityPolicy:
  enabled: false
podSecurityPolicy:
  enabled: true
prometheus-node-exporter
prometheus-node-exporter:
  containerSecurityContext:
    allowPrivilegeEscalation: false
  enabled: true
  rbac:
    pspEnabled: false
prometheus-pushgateway
prometheus-pushgateway:
  enabled: true
  serviceAnnotations:
    prometheus.io/probe: pushgateway
rbacWhether to create rbac.
rbac:
  create: true
ruleFiles
ruleFiles: {}
scrapeConfigFiles
scrapeConfigFiles: []
serverConfigure the server component.
Expand
server:
  affinity: {}
  alertmanagers: []
  automountServiceAccountToken: false
  baseURL: ''
  clusterRoleNameOverride: ''
  command: []
  configMapAnnotations: {}
  configMapOverrideName: ''
  configPath: /etc/config/prometheus.yml
  containerSecurityContext: {}
  defaultFlagsOverride: []
  deploymentAnnotations: {}
  dnsConfig: {}
  dnsPolicy: ClusterFirst
  emptyDir:
    sizeLimit: ''
  enableServiceLinks: true
  env: []
  exemplars: {}
  extraArgs: {}
  extraConfigmapLabels: {}
  extraConfigmapMounts: []
  extraFlags:
  - web.enable-lifecycle
  extraHostPathMounts: []
  extraInitContainers: []
  extraSecretMounts: []
  extraVolumeMounts: []
  extraVolumes: []
  global:
    evaluation_interval: 1m
    scrape_interval: 1m
    scrape_timeout: 10s
  hostAliases: []
  hostNetwork: false
  image:
    digest: ''
    pullPolicy: IfNotPresent
    repository: quay.io/prometheus/prometheus
    tag: ''
  ingress:
    annotations: {}
    enabled: false
    extraLabels: {}
    extraPaths: []
    hosts: []
    path: /
    pathType: Prefix
    tls: []
  livenessProbeFailureThreshold: 3
  livenessProbeInitialDelay: 30
  livenessProbePeriodSeconds: 15
  livenessProbeSuccessThreshold: 1
  livenessProbeTimeout: 10
  name: server
  nodeSelector: {}
  persistentVolume:
    accessModes:
    - ReadWriteOnce
    annotations: {}
    enabled: true
    existingClaim: ''
    labels: {}
    mountPath: /data
    size: 8Gi
    statefulSetNameOverride: ''
    subPath: ''
  podAnnotations: {}
  podAntiAffinity: ''
  podAntiAffinityTopologyKey: kubernetes.io/hostname
  podDisruptionBudget:
    enabled: false
    maxUnavailable: 1
  podLabels: {}
  podSecurityPolicy:
    annotations: {}
  portName: ''
  prefixURL: ''
  priorityClassName: ''
  probeHeaders: []
  probeScheme: HTTP
  readinessProbeFailureThreshold: 3
  readinessProbeInitialDelay: 30
  readinessProbePeriodSeconds: 5
  readinessProbeSuccessThreshold: 1
  readinessProbeTimeout: 4
  releaseNamespace: false
  remoteRead: []
  remoteWrite: []
  replicaCount: 1
  resources: {}
  retention: 15d
  retentionSize: ''
  revisionHistoryLimit: 10
  securityContext:
    fsGroup: 65534
    runAsGroup: 65534
    runAsNonRoot: true
    runAsUser: 65534
  service:
    additionalPorts: []
    annotations: {}
    clusterIP: ''
    enabled: true
    externalIPs: []
    gRPC:
      enabled: false
      servicePort: 10901
    labels: {}
    loadBalancerIP: ''
    loadBalancerSourceRanges: []
    servicePort: 80
    sessionAffinity: None
    statefulsetReplica:
      enabled: false
      replica: 0
    type: ClusterIP
  sidecarContainers: {}
  sidecarTemplateValues: {}
  startupProbe:
    enabled: false
    failureThreshold: 30
    periodSeconds: 5
    timeoutSeconds: 10
  statefulSet:
    annotations: {}
    enabled: false
    headless:
      annotations: {}
      gRPC:
        enabled: false
        servicePort: 10901
      labels: {}
      servicePort: 80
    labels: {}
    podManagementPolicy: OrderedReady
    pvcDeleteOnStsDelete: false
    pvcDeleteOnStsScale: false
  storagePath: ''
  strategy:
    type: Recreate
  tcpSocketProbeEnabled: false
  terminationGracePeriodSeconds: 300
  tolerations: []
  topologySpreadConstraints: []
  tsdb: {}
  useExistingClusterRoleName: false
  verticalAutoscaler:
    enabled: false
server.automountServiceAccountTokenOpt out of automounting Kubernetes API credentials. If set it will override serviceAccounts.server.automountServiceAccountToken value for ServiceAccount.
server:
  automountServiceAccountToken: false
server.clusterRoleNameOverrideIf set it will override prometheus.server.fullname value for ClusterRole and ClusterRoleBinding
server:
  clusterRoleNameOverride: ''
server.namePrometheus server container name
server:
  name: server
server.useExistingClusterRoleNameUse a ClusterRole (and ClusterRoleBinding). If set to false, we define a RoleBinding in the defined namespaces ONLY. NB: because we need a Role with nonResourceURL's ("/metrics") - you must get someone with Cluster-admin privileges to define this role for you, before running with this setting enabled. This makes prometheus work - for users who do not have ClusterAdmin privs, but wants prometheus to operate on their own namespaces, instead of clusterwide. You MUST also set namespaces to the ones you have access to and want monitored by Prometheus.
server:
  useExistingClusterRoleName: false
serverFiles
Expand
serverFiles:
  alerting_rules.yml: {}
  alerts: {}
  prometheus.yml:
    rule_files:
    - /etc/config/recording_rules.yml
    - /etc/config/alerting_rules.yml
    - /etc/config/rules
    - /etc/config/alerts
    scrape_configs:
    - job_name: prometheus
      static_configs:
      - targets:
        - localhost:9090
    - bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
      job_name: kubernetes-apiservers
      kubernetes_sd_configs:
      - role: endpoints
      relabel_configs:
      - action: keep
        regex: default;kubernetes;https
        source_labels:
        - meta_kubernetes_namespace
        - __meta_kubernetes_service_name
        - __meta_kubernetes_endpoint_port_name
      scheme: https
      tls_config:
        ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
        insecure_skip_verify: true
    - bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
      job_name: kubernetes-nodes
      kubernetes_sd_configs:
      - role: node
      relabel_configs:
      - action: labelmap
        regex: __meta_kubernetes_node_label_(.+)
      - replacement: kubernetes.default.svc:443
        target_label: __address
      - regex: (.+)
        replacement: /api/v1/nodes/$1/proxy/metrics
        source_labels:
        - meta_kubernetes_node_name
        target_label: __metrics_path
      scheme: https
      tls_config:
        ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
        insecure_skip_verify: true
    - bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
      job_name: kubernetes-nodes-cadvisor
      kubernetes_sd_configs:
      - role: node
      relabel_configs:
      - action: labelmap
        regex: meta_kubernetes_node_label_(.+)
      - replacement: kubernetes.default.svc:443
        target_label: __address
      - regex: (.+)
        replacement: /api/v1/nodes/$1/proxy/metrics/cadvisor
        source_labels:
        - meta_kubernetes_node_name
        target_label: __metrics_path
      scheme: https
      tls_config:
        ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
        insecure_skip_verify: true
    - honor_labels: true
      job_name: kubernetes-service-endpoints
      kubernetes_sd_configs:
      - role: endpoints
      relabel_configs:
      - action: keep
        regex: true
        source_labels:
        - meta_kubernetes_service_annotation_prometheus_io_scrape
      - action: drop
        regex: true
        source_labels:
        - __meta_kubernetes_service_annotation_prometheus_io_scrape_slow
      - action: replace
        regex: (https?)
        source_labels:
        - __meta_kubernetes_service_annotation_prometheus_io_scheme
        target_label: __scheme
      - action: replace
        regex: (.+)
        source_labels:
        - meta_kubernetes_service_annotation_prometheus_io_path
        target_label: __metrics_path
      - action: replace
        regex: (.+?)(?::\d+)?;(\d+)
        replacement: $1:$2
        source_labels:
        - address
        - meta_kubernetes_service_annotation_prometheus_io_port
        target_label: __address
      - action: labelmap
        regex: meta_kubernetes_service_annotation_prometheus_io_param_(.+)
        replacement: __param_$1
      - action: labelmap
        regex: __meta_kubernetes_service_label_(.+)
      - action: replace
        source_labels:
        - __meta_kubernetes_namespace
        target_label: namespace
      - action: replace
        source_labels:
        - __meta_kubernetes_service_name
        target_label: service
      - action: replace
        source_labels:
        - __meta_kubernetes_pod_node_name
        target_label: node
    - honor_labels: true
      job_name: kubernetes-service-endpoints-slow
      kubernetes_sd_configs:
      - role: endpoints
      relabel_configs:
      - action: keep
        regex: true
        source_labels:
        - __meta_kubernetes_service_annotation_prometheus_io_scrape_slow
      - action: replace
        regex: (https?)
        source_labels:
        - __meta_kubernetes_service_annotation_prometheus_io_scheme
        target_label: __scheme
      - action: replace
        regex: (.+)
        source_labels:
        - meta_kubernetes_service_annotation_prometheus_io_path
        target_label: __metrics_path
      - action: replace
        regex: (.+?)(?::\d+)?;(\d+)
        replacement: $1:$2
        source_labels:
        - address
        - meta_kubernetes_service_annotation_prometheus_io_port
        target_label: __address
      - action: labelmap
        regex: meta_kubernetes_service_annotation_prometheus_io_param_(.+)
        replacement: __param_$1
      - action: labelmap
        regex: __meta_kubernetes_service_label_(.+)
      - action: replace
        source_labels:
        - __meta_kubernetes_namespace
        target_label: namespace
      - action: replace
        source_labels:
        - __meta_kubernetes_service_name
        target_label: service
      - action: replace
        source_labels:
        - __meta_kubernetes_pod_node_name
        target_label: node
      scrape_interval: 5m
      scrape_timeout: 30s
    - honor_labels: true
      job_name: prometheus-pushgateway
      kubernetes_sd_configs:
      - role: service
      relabel_configs:
      - action: keep
        regex: pushgateway
        source_labels:
        - __meta_kubernetes_service_annotation_prometheus_io_probe
    - honor_labels: true
      job_name: kubernetes-services
      kubernetes_sd_configs:
      - role: service
      metrics_path: /probe
      params:
        module:
        - http_2xx
      relabel_configs:
      - action: keep
        regex: true
        source_labels:
        - __meta_kubernetes_service_annotation_prometheus_io_probe
      - source_labels:
        - __address
        target_label: param_target
      - replacement: blackbox
        target_label: __address
      - source_labels:
        - param_target
        target_label: instance
      - action: labelmap
        regex: __meta_kubernetes_service_label_(.+)
      - source_labels:
        - __meta_kubernetes_namespace
        target_label: namespace
      - source_labels:
        - __meta_kubernetes_service_name
        target_label: service
    - honor_labels: true
      job_name: kubernetes-pods
      kubernetes_sd_configs:
      - role: pod
      relabel_configs:
      - action: keep
        regex: true
        source_labels:
        - __meta_kubernetes_pod_annotation_prometheus_io_scrape
      - action: drop
        regex: true
        source_labels:
        - __meta_kubernetes_pod_annotation_prometheus_io_scrape_slow
      - action: replace
        regex: (https?)
        source_labels:
        - __meta_kubernetes_pod_annotation_prometheus_io_scheme
        target_label: __scheme
      - action: replace
        regex: (.+)
        source_labels:
        - meta_kubernetes_pod_annotation_prometheus_io_path
        target_label: __metrics_path
      - action: replace
        regex: (\d+);(([A-Fa-f0-9]{1,4}::?){1,7}[A-Fa-f0-9]{1,4})
        replacement: '[$2]:$1'
        source_labels:
        - meta_kubernetes_pod_annotation_prometheus_io_port
        - __meta_kubernetes_pod_ip
        target_label: __address
      - action: replace
        regex: (\d+);((([0-9]+?)(.|$)){4})
        replacement: $2:$1
        source_labels:
        - meta_kubernetes_pod_annotation_prometheus_io_port
        - __meta_kubernetes_pod_ip
        target_label: __address
      - action: labelmap
        regex: meta_kubernetes_pod_annotation_prometheus_io_param_(.+)
        replacement: __param_$1
      - action: labelmap
        regex: __meta_kubernetes_pod_label_(.+)
      - action: replace
        source_labels:
        - __meta_kubernetes_namespace
        target_label: namespace
      - action: replace
        source_labels:
        - __meta_kubernetes_pod_name
        target_label: pod
      - action: drop
        regex: Pending|Succeeded|Failed|Completed
        source_labels:
        - __meta_kubernetes_pod_phase
      - action: replace
        source_labels:
        - __meta_kubernetes_pod_node_name
        target_label: node
    - honor_labels: true
      job_name: kubernetes-pods-slow
      kubernetes_sd_configs:
      - role: pod
      relabel_configs:
      - action: keep
        regex: true
        source_labels:
        - __meta_kubernetes_pod_annotation_prometheus_io_scrape_slow
      - action: replace
        regex: (https?)
        source_labels:
        - __meta_kubernetes_pod_annotation_prometheus_io_scheme
        target_label: __scheme
      - action: replace
        regex: (.+)
        source_labels:
        - meta_kubernetes_pod_annotation_prometheus_io_path
        target_label: __metrics_path
      - action: replace
        regex: (\d+);(([A-Fa-f0-9]{1,4}::?){1,7}[A-Fa-f0-9]{1,4})
        replacement: '[$2]:$1'
        source_labels:
        - meta_kubernetes_pod_annotation_prometheus_io_port
        - __meta_kubernetes_pod_ip
        target_label: __address
      - action: replace
        regex: (\d+);((([0-9]+?)(.|$)){4})
        replacement: $2:$1
        source_labels:
        - meta_kubernetes_pod_annotation_prometheus_io_port
        - __meta_kubernetes_pod_ip
        target_label: __address
      - action: labelmap
        regex: __meta_kubernetes_pod_annotation_prometheus_io_param_(.+)
        replacement: __param_$1
      - action: labelmap
        regex: __meta_kubernetes_pod_label_(.+)
      - action: replace
        source_labels:
        - __meta_kubernetes_namespace
        target_label: namespace
      - action: replace
        source_labels:
        - __meta_kubernetes_pod_name
        target_label: pod
      - action: drop
        regex: Pending|Succeeded|Failed|Completed
        source_labels:
        - __meta_kubernetes_pod_phase
      - action: replace
        source_labels:
        - __meta_kubernetes_pod_node_name
        target_label: node
      scrape_interval: 5m
      scrape_timeout: 30s
  recording_rules.yml: {}
  rules: {}
serviceAccountsDefine serviceAccount names for components. Defaults to component's fully qualified name.
serviceAccounts:
  server:
    annotations: {}
    automountServiceAccountToken: false
    create: true
    name: ''
serviceAccounts.server.automountServiceAccountTokenOpt out of automounting Kubernetes API credentials. It will be overriden by server.automountServiceAccountToken value, if set.
serviceAccounts:
  server:
    automountServiceAccountToken: false
+

Automatic helm documentation generated using very-doge-wow/stella.

+
+
+ + + + diff --git a/README.md b/README.md index 9f18afc..b56c422 100644 --- a/README.md +++ b/README.md @@ -66,11 +66,11 @@ python stella.py --help ```text -usage: stella.py [-h] [-hcp HELM_CHART_PATH] [-o OUTPUT] [-t TEMPLATE] [-fh] [-css CSS] [-v] +usage: stella.py [-h] [-hcp HELM_CHART_PATH] [-o OUTPUT] [-t TEMPLATE] [-fh] [-ah] [-css CSS] [-v] Will create documentation for helm charts using metadata. -optional arguments: +options: -h, --help show this help message and exit -hcp HELM_CHART_PATH, --helm-chart-path HELM_CHART_PATH Path to helm chart (default `.`). @@ -79,11 +79,17 @@ optional arguments: -t TEMPLATE, --template TEMPLATE Custom template file. -fh, --format-html Output using html instead of md. + -ah, --advanced-html Output using html instead of md with additional features. -css CSS, --css CSS Path to optional css file to use for html generation (use in conjunction with -fh). -v, --verbose Activate debug logging. ``` +The option `--advanced-html` can't be used with custom CSS, as it offers some +additional functionality which would break when using custom CSS. It will +create a static html site with dynamic navbar and a search for the chart's +values. + ## Adding `stella` Docstrings to your Chart Metadata is read from the present files of your chart. diff --git a/stella.py b/stella.py index f27efa7..680f01d 100755 --- a/stella.py +++ b/stella.py @@ -12,6 +12,8 @@ parser.add_argument("-o", "--output", help="Output file (default `output.md`).", required=False, default="output.md") parser.add_argument("-t", "--template", help="Custom template file.", required=False, default="") parser.add_argument("-fh", "--format-html", help="Output using html instead of md.", required=False, action="store_true") + parser.add_argument("-ah", "--advanced-html", help="Output using html instead of md with additional features.", required=False, + action="store_true") parser.add_argument("-css", "--css", help="Path to optional css file to use for html generation (use in " "conjunction with -fh).", required=False, default="") parser.add_argument("-v", "--verbose", help="Activate debug logging.", required=False, action="store_true") @@ -30,6 +32,7 @@ logging.debug(f"--output: {args.output}") logging.debug(f"--template: {args.template}") logging.debug(f"--format-html: {args.format_html}") + logging.debug(f"--format-html: {args.advanced_html}") logging.debug(f"--css: {args.css}") logging.debug(f"--verbose: {args.verbose}") @@ -43,7 +46,7 @@ args.output = args.output.replace(".md", ".html") # write doc from gathered data - doc_writer.write(output=args.output, doc=result, template=args.template, format_html=args.format_html, css=args.css) + doc_writer.write(output=args.output, doc=result, template=args.template, format_html=args.format_html, advanced_html=args.advanced_html, css=args.css) except Exception as err: logging.exception("Error occured.") exit(1) diff --git a/writer/doc_writer.py b/writer/doc_writer.py index 4dd6756..591c1a6 100644 --- a/writer/doc_writer.py +++ b/writer/doc_writer.py @@ -3,7 +3,7 @@ import markdown -def write(output: str, doc: dict, template: str, format_html: bool, css: str) -> str: +def write(output: str, doc: dict, template: str, format_html: bool, advanced_html: bool, css: str) -> str: """ Creates a Markdown doc file for the helm chart. Uses a custom template if present, else uses a default template. @@ -12,6 +12,7 @@ def write(output: str, doc: dict, template: str, format_html: bool, css: str) -> doc (dict): Data structure containing all relevant helm chart information. template (str): Path to custom template. If value is empty, uses default template. format_html (bool): Whether to convert the finished md to html before writing to file. + advanced_html (bool): Whether to use the advanced html template to render the md file. css (str): Path to optional css file for html generation. """ logging.debug("starting to write doc from generated data") @@ -88,28 +89,237 @@ def write(output: str, doc: dict, template: str, format_html: bool, css: str) -> logging.debug("writing output to file") - with open(output, "w") as file: - if format_html: - logging.debug("converting md to html before write") - result = markdown.markdown(result, extensions=["tables"]) - if css != "": - logging.debug("adding custom css to html before write") - with open(css, "r") as style: - result = f""" + html_simple_template = """ -{result} +REPLACE_STRING_BODY """ + + html_advanced_template = r""" + + + + + pipeship-application + + + + +
+
+ REPLACE_STRING_BODY +
+
+ + + + +""" + + with (open(output, "w") as file): + if format_html: + logging.debug("converting md to html before write") + result = markdown.markdown(result, extensions=["tables"]) + if format_html and not advanced_html: + if css != "": + logging.debug("adding custom css to html before write") + with open(css, "r") as style: + result = html_simple_template.replace("REPLACE_STRING_STYLE", style.read()).replace("REPLACE_STRING_BODY", result) + elif format_html: + logging.debug("converting md to html before write using advanced html") + result = html_advanced_template.replace("REPLACE_STRING_BODY", result) # simply output the text (md or html, don't care) file.write(result) diff --git a/writer/doc_writer_test.py b/writer/doc_writer_test.py index 10f1359..93df371 100644 --- a/writer/doc_writer_test.py +++ b/writer/doc_writer_test.py @@ -171,7 +171,7 @@ def test_writer_keywords_custom_template(): ] } - result = doc_writer.write("test/output.md", doc, "test/custom-template-keywords.md", False, "") + result = doc_writer.write("test/output.md", doc, "test/custom-template-keywords.md", False, False,"") assert result == """unittest 1.0 @@ -244,7 +244,7 @@ def test_writer_keywords_default_template(): ] } - result = doc_writer.write("test/output.md", doc, "", False, "") + result = doc_writer.write("test/output.md", doc, "", False, False, "") assert result == """ # unittest @@ -316,7 +316,7 @@ def test_writer_empty(): ] } - result = doc_writer.write("test/output.md", doc, "", False, "") + result = doc_writer.write("test/output.md", doc, "", False, False, "") assert result == """ # unittest ![Version: 1.0](https://img.shields.io/badge/Version-1.0-informational?style=flat-square) ![Version: 1.1](https://img.shields.io/badge/appVersion-1.1-informational?style=flat-square) ![Version: 1.2](https://img.shields.io/badge/apiVersion-1.2-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) @@ -403,7 +403,7 @@ def test_writer_html(): ] } - result = doc_writer.write("test/output.md", doc, "", True, "") + result = doc_writer.write("test/output.md", doc, "", True, False, "") assert result == """

unittest

Version: 1.0 Version: 1.1 Version: 1.2 Type: application

Description

@@ -453,6 +453,283 @@ def test_writer_html():

Automatic helm documentation generated using very-doge-wow/stella.

""" +def test_writer_advanced_html(): + doc = { + "type": "application", + "version": "1.0", + "appVersion": "1.1", + "apiVersion": "1.2", + "name": "unittest", + "description": "simple templating test", + "dependencies": [], + "templates": [], + "objects": [ + { + "kind": "Ingress", + "from Template": "template.yaml" + } + ], + "values": [ + { + "name": "ReplicaCount", + "description": "how many replicas to deploy", + "default": "1", + "example": "replicaCount: 2" + } + ] + } + + result = doc_writer.write("test/output.md", doc, "", True, True, "") + assert result == r""" + + + + + pipeship-application + + + + +
+
+

unittest

+

Version: 1.0 Version: 1.1 Version: 1.2 Type: application

+

Description

+

simple templating test

+

Dependencies

+

This chart depends on the following subcharts.

+

No dependencies found.

+

Templates

+

The following templates will be deployed.

+

No templates found.

+

Objects

+

The aforementioned templates will deploy the following objects.

+ + + + + + + + + + + + + +
KindFrom template
Ingresstemplate.yaml
+

Values

+

The following values can/will be used for deployments.

+ + + + + + + + + + + + + + + + + +
NameDescriptionDefaultExample
ReplicaCounthow many replicas to deploy
1
replicaCount: 2
+

Automatic helm documentation generated using very-doge-wow/stella.

+
+
+ + + + +""" + + def test_writer_html_custom_css(): doc = { "type": "application", @@ -479,7 +756,7 @@ def test_writer_html_custom_css(): ] } - result = doc_writer.write("test/output.md", doc, "", True, "test/style.css") + result = doc_writer.write("test/output.md", doc, "", True, False, "test/style.css") assert result == """