Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/oskarstark/doctor-rst
Bring consistency to documentation
https://github.com/oskarstark/doctor-rst
docker docs hacktoberfest php rst sphinx
Last synced: 2 days ago
JSON representation
Bring consistency to documentation
- Host: GitHub
- URL: https://github.com/oskarstark/doctor-rst
- Owner: OskarStark
- License: mit
- Created: 2018-12-27T09:19:36.000Z (about 6 years ago)
- Default Branch: develop
- Last Pushed: 2024-10-29T10:51:41.000Z (2 months ago)
- Last Synced: 2024-10-29T12:45:51.355Z (2 months ago)
- Topics: docker, docs, hacktoberfest, php, rst, sphinx
- Language: PHP
- Homepage:
- Size: 5.28 MB
- Stars: 36
- Watchers: 5
- Forks: 21
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
DOCtor-RST
==========
Lint your documentation against given rules.
Available rules
---------------
You can find the available rules [here](docs/rules.md).
Usage
-----
You can use it as a Github Action like this:
```yaml
# .github/workflows/lint.yaml
name: Lint
on:
push:
pull_request:
jobs:
doctor-rst:
name: DOCtor-RST
runs-on: ubuntu-latest
steps:
- name: "Checkout code"
uses: actions/checkout@v4
- name: DOCtor-RST
uses: docker://oskarstark/doctor-rst
with:
args: --short --error-format=github
```
If your `*.rst` files are not located in root:
```diff
uses: docker://oskarstark/doctor-rst
with:
args: --short --error-format=github
+ env:
+ DOCS_DIR: 'docs/'
```
Error Formatter
---------------
* **detect** _(default)_ If running inside GithubActions CI environment, `github` is used, otherwise `console`.
* **github** Used to annotate your pull requests.
* **console** Used to generate a human readable output.
To force the usage of a specific formatter, use the `--error-format` option.
Use Caching to Speedup your GithubActions builds
----------------------------------
```diff
steps:
- name: "Checkout"
uses: actions/checkout@v4
+ - name: "Create cache dir"
+ run: mkdir .cache
+
+ - name: "Extract base branch name"
+ run: echo "##[set-output name=branch;]$(echo ${GITHUB_BASE_REF:=${GITHUB_REF##*/}})"
+ id: extract_base_branch
+
+ - name: "Cache DOCtor-RST"
+ uses: actions/cache@v2
+ with:
+ path: .cache
+ key: doctor-rst-${{ runner.os }}-${{ steps.extract_base_branch.outputs.branch }}
+ restore-keys: |
+ doctor-rst-${{ runner.os }}-
+ doctor-rst-
+
- name: "Run DOCtor-RST"
uses: docker://oskarstark/doctor-rst
with:
- args: --short --error-format=github
+ args: --short --error-format=github --cache-file=/github/workspace/.cache/doctor-rst.cache
```
Docker
------
A Docker-Image is built automatically and located here:
https://cloud.docker.com/u/oskarstark/repository/docker/oskarstark/doctor-rst
You can run it in any given directory like this:
`docker run --rm -it -e DOCS_DIR='/docs' -v ${PWD}:/docs oskarstark/doctor-rst:latest`
Local usage
-----------
`bin/doctor-rst analyze dummy --group=@Symfony`
or
`bin/doctor-rst analyze dummy --group=@Sonata`
Todos
-----
* Allow to register custom Rules
* Move logic from Command to Services