Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/flavienbwk/freshdoc
Keep code and text snippets in sync across your git repos.
https://github.com/flavienbwk/freshdoc
ci documentation gitops sdlc
Last synced: 5 days ago
JSON representation
Keep code and text snippets in sync across your git repos.
- Host: GitHub
- URL: https://github.com/flavienbwk/freshdoc
- Owner: flavienbwk
- License: mit
- Created: 2023-05-12T23:01:45.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-07-15T10:33:56.000Z (over 1 year ago)
- Last Synced: 2024-11-30T05:12:07.390Z (2 months ago)
- Topics: ci, documentation, gitops, sdlc
- Language: Python
- Homepage:
- Size: 489 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Freshdoc
Keep code and text snippets in sync across your git repos.
Useful to track any evolving info stored in your documentations, such as **team members' names**, **phone numbers**, **e-mail addresses** or **server IPs** across your repos.
## Features
- Check for non-identical text snippets accross repos
- Detect dead links
- Integrates with any git repo
- Callable through [curl](https://curl.se/)
## Usage
### Declare a reference
Wrap text or code to be tracked in a markdown comment including a Freshdoc reference tag.
```markdown
# My incredible documentation
## Support
Current team includes :
- Juliet CAPULET
- Antigone THEBAN
- Jean VALJEAN
Phone number : +33900000001
```
### Validate in GitLab CI
Use it with _curl_ :
```yaml
stages:
- test
freshdoc:
stage: test
script:
- apk update && apk add bash curl jq
- |
#!/bin/bash
response=(curl --request POST \
--max-time 30 -s -w "\n%{http_code}" \
-H "Content-Type=application/x-www-form-urlencoded" \
-d "repos_to_check=https://gitlab-ci-token:${CI_JOB_TOKEN}@mygitlab.com/${CI_PROJECT_PATH_SLUG},https://gitlab-ci-token:${CI_JOB_TOKEN}@mygitlab.com/group2/project2" \
-d "branches_to_check=main,master,develop,${CI_COMMIT_BRANCH}" \
-d "ssl_verify=true" \
-d "file_extensions=md,txt" \
-d "excluded_directories=node_modules/**" \
-d "check_dead_links=true" \
-d "verbose=false" \
http://localhost:8080/check)
http_code=$(echo "$response" | tail -n 1)
payload=$(echo "$response" | head -n -1)
echo "$payload" | jq -r
if [ "$response_code" != "200" ]; then
echo "Freshdoc returned a non-200 HTTP code : check the logs above."
exit 1
fi
```
- A `200` HTTP code will be returned if no problem was encountered, otherwise `400`.
- Body with eventually include a detailed list of problems to solve.
| Parameter | Value description |
| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **repos_to_check** | Required. Commas-delimited list of repo URLs to track references. Optionally include credentials with this format : _https://{username}:{password}@mygitserver.com/group/project_. |
| **branches_to_check** | Default: "main,master,develop". Commas-delimited list of branches to track. Unexistant branches will be skipped. |
| [**ssl_verify**](https://stackoverflow.com/questions/11621768/how-can-i-make-git-accept-a-self-signed-certificate) | "true" (default) or "false". Enable or disable git clone command's SSL verification for provided repos. |
| **file_extensions** | Default: "md,txt". Commas-delimited list of file extensions in which Freshdoc will check for references. |
| **excluded_directories** | No default value. Commas-delimited list of glob patterns indicating which directory to ignore for all provided repos. |
| **check_dead_links** | "true" (default) or "false". Checks if links are valid (responsive and HTTP code between 200 and 403). Only checks the first repo from the REPOS_TO_CHECK list. |
| **verbose** | "true" or "false" (default). Returns analysis details in response. Useful for debugging. |
## Start server
Using Docker and docker-compose :
```bash
docker-compose -f prod.docker-compose.yml up --build -d
```
API will be available on port `8080` by default.
## Syntax
The Freshdoc tag is composed of 3 items. Let's take an example :
```markdown
text
```
- `fd` is for identifying a Freshdoc tag in a file
- `ref_name` is a small name to identify the snippet to track
- `1` is the version of your snippet to make it upgradable
> `` are optional. Freshdoc is matching any tag found under the `` format in the content of a file.
## Upgrading a reference
Let's say you have two repos A and B to keep in sync. To upgrade a reference, increase its version number in repo A, commit and push.
Now-on, any push in repo B will trigger a warning until the **value** and **version** of the reference are matching.