diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7b40242..1adacc2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,23 +10,23 @@ Before embarking on a more ambitious contribution, please quickly [get in touch] For general questions or support requests, please refer to the [discussion section](https://github.com/DS4SD/docling/discussions). -**Note: We appreciate your effort, and want to avoid a situation where a contribution -requires extensive rework (by you or by us), sits in backlog for a long time, or +**Note: We appreciate your effort and want to avoid situations where a contribution +requires extensive rework (by you or by us), sits in the backlog for a long time, or cannot be accepted at all!** -### Proposing new features +### Proposing New Features If you would like to implement a new feature, please [raise an issue](https://github.com/DS4SD/docling/issues) before sending a pull request so the feature can be discussed. This is to avoid -you wasting your valuable time working on a feature that the project developers -are not interested in accepting into the code base. +you spending valuable time working on a feature that the project developers +are not interested in accepting into the codebase. -### Fixing bugs +### Fixing Bugs If you would like to fix a bug, please [raise an issue](https://github.com/DS4SD/docling/issues) before sending a pull request so it can be tracked. -### Merge approval +### Merge Approval The project maintainers use LGTM (Looks Good To Me) in comments on the code review to indicate acceptance. A change requires LGTMs from two of the @@ -38,7 +38,7 @@ For a list of the maintainers, see the [MAINTAINERS.md](MAINTAINERS.md) page. ## Legal Each source file must include a license header for the MIT -Software. Using the SPDX format is the simplest approach. +Software. Using the SPDX format is the simplest approach, e.g. ``` @@ -84,29 +84,27 @@ Please feel free to connect with us using the [discussion section](https://githu We use Poetry to manage dependencies. +#### Installation -#### Install +To install Poetry, follow the documentation here: https://python-poetry.org/docs/master/#installing-with-the-official-installer -To install, see the documentation here: https://python-poetry.org/docs/master/#installing-with-the-official-installer - -1. Install the Poetry globally in your machine +1. Install Poetry globally on your machine: ```bash curl -sSL https://install.python-poetry.org | python3 - ``` The installation script will print the installation bin folder `POETRY_BIN` which you need in the next steps. -2. Make sure Poetry is in your `$PATH` - - for `zsh` +2. Make sure Poetry is in your `$PATH`: + - for `zsh`: ```sh echo 'export PATH="POETRY_BIN:$PATH"' >> ~/.zshrc ``` - - for `bash` + - for `bash`: ```sh echo 'export PATH="POETRY_BIN:$PATH"' >> ~/.bashrc ``` -3. The official guidelines linked above include useful details on the configuration of autocomplete for most shell environments, e.g. Bash and Zsh. - +3. The official guidelines linked above include useful details on configuring autocomplete for most shell environments, e.g., Bash and Zsh. #### Create a Virtual Environment and Install Dependencies @@ -116,7 +114,7 @@ To activate the Virtual Environment, run: poetry shell ``` -To spawn a shell with the Virtual Environment activated. If the Virtual Environment doesn't exist, Poetry will create one for you. Then, to install dependencies, run: +This will spawn a shell with the Virtual Environment activated. If the Virtual Environment doesn't exist, Poetry will create one for you. Then, to install dependencies, run: ```bash poetry install @@ -124,30 +122,28 @@ poetry install **(Advanced) Use a Specific Python Version** -If for whatever reason you need to work in a specific (older) version of Python, run: +If you need to work with a specific (older) version of Python, run: ```bash poetry env use $(which python3.8) ``` -This creates a Virtual Environment with Python 3.8. For other versions, replace `$(which python3.8)` by the path to the interpreter (e.g., `/usr/bin/python3.8`) or use `$(which pythonX.Y)`. +This creates a Virtual Environment with Python 3.8. For other versions, replace `$(which python3.8)` with the path to the interpreter (e.g., `/usr/bin/python3.8`) or use `$(which pythonX.Y)`. - -#### Add a new dependency +#### Add a New Dependency ```bash poetry add NAME ``` -## Coding style guidelines +## Coding Style Guidelines We use the following tools to enforce code style: - iSort, to sort imports - Black, to format code - -We run a series of checks on the code base on every commit, using `pre-commit`. To install the hooks, run: +We run a series of checks on the codebase on every commit using `pre-commit`. To install the hooks, run: ```bash pre-commit install @@ -155,27 +151,25 @@ pre-commit install To run the checks on-demand, run: -``` +```bash pre-commit run --all-files ``` -Note: Checks like `Black` and `isort` will "fail" if they modify files. This is because `pre-commit` doesn't like to see files modified by their Hooks. In these cases, `git add` the modified files and `git commit` again. - - +Note: Checks like `Black` and `isort` will "fail" if they modify files. This is because `pre-commit` doesn't like to see files modified by its hooks. In these cases, `git add` the modified files and `git commit` again. ## Documentation We use [MkDocs](https://www.mkdocs.org/) to write documentation. -To run the documentation server, do: +To run the documentation server, run: ```bash mkdocs serve ``` -The server will be available on [http://localhost:8000](http://localhost:8000). +The server will be available at [http://localhost:8000](http://localhost:8000). -### Pushing Documentation to GitHub pages +### Pushing Documentation to GitHub Pages Run the following: