Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Linting] Check syntax and format code blocks in markdown with blacken-docs #5803

Merged
merged 5 commits into from
Jun 23, 2024

Conversation

jond01
Copy link
Member

@jond01 jond01 commented Jun 19, 2024

https://github.com/adamchainz/blacken-docs

This change introduces the following benefits:

  1. Ensure code blocks in the docs are coherent syntax-wise.
  2. Format them according to Black conventions.

Add a new phony target, make fmt-docs, and enforce it as part of make lint, which runs in the CI workflow.

Some examples of wrong syntax in the docs before this PR:

  1. Missing closing parenthesis ):
    ```python
    model_name = "RandomForestClassifier"
    project.log_model(
    model_name,
    model_file="./assets/model.pkl",
    training_set=train_set,
    framework="sklearn",
    ```
  2. Missing trailing comma , in L61 and L62:
    # Create a function from py or notebook (ipynb) file
    get_data_func = project.set_function('./get_data.py'
    name='get_data'
    kind='job',
    image='mlrun/mlrun')
  3. Not a Python code block:
    ```python
    s3://<bucket name>/projects/{{run.project}}/artifacts
    ```
  4. Function body (... placeholder) unindented:
    ``` python
    @mlrun.handler(labels={'framework':'scikit-learn'},
    outputs=['prediction:dataset'])
    def train_and_predict(train_data: pd.DataFrame,
    predict_input: pd.DataFrame,
    label_column='label'):
    ...
    ```

There are many more wrong syntax examples, but they are all fixed here.

Note: I previously configured Ruff to check and format code blocks inside Python/Jupyter Notebooks, such as code blocks in docstrings.
However, it's not designed to run on markdown files.

Copy link
Member

@moranbental moranbental left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks very good, just one comment

Makefile Outdated Show resolved Hide resolved
@assaf758 assaf758 merged commit a0adb21 into mlrun:development Jun 23, 2024
11 checks passed
@jond01 jond01 deleted the task/add-blacken-docs branch June 23, 2024 12:46
jond01 added a commit to jond01/mlrun that referenced this pull request Jun 24, 2024
`blacken-docs` depends on `black` but doesn't
pin its version.
Pin the version to avoid incompatible versions on
dev machines.
`blacken-docs` was added in mlrun#5803.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants