Docs: Build Documentation for Ormdantic

.github/workflows/docs.yml

@@ -0,0 +1,40 @@
+name: Build Docs
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-18.04
+    steps:
+      - name: Dump GitHub context
+        env:
+          GITHUB_CONTEXT: ${{ toJson(github) }}
+        run: echo "$GITHUB_CONTEXT"
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.9"
+      - uses: actions/cache@v3
+        id: cache
+        with:
+          path: ${{ env.pythonLocation }}
+          key: ${{ runner.os }}-python-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-docs
+      - name: Install Flit
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: python3.9 -m pip install flit
+      - name: Install docs extras
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: python3.9 -m flit install --deps production --extras docs
+      - name: Build docs
+        run: mkdocs build -d build
+
+      - name: Deploy docs
+        uses: jsmrcaga/action-netlify-deploy@v1.1.0
+        with:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+          NETLIFY_DEPLOY_TO_PROD: true
+          NETLIFY_DEPLOY_MESSAGE: "Prod deploy v${{ github.ref }}"

docs/code_of_conduct.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of
+experience, nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, or to ban temporarily or permanently any
+contributor for other behaviors that they deem inappropriate, threatening,
+offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at yasserth19@gmail.com. The project
+team will review and investigate all complaints, and will respond in a way that
+it deems appropriate to the circumstances. The project team is obligated to
+maintain confidentiality with regard to the reporter of an incident. Further
+details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

docs/contributing.md

@@ -0,0 +1,251 @@
+# Development - Contributing 🐣
+
+If you already cloned the repository and you know that you need to deep dive
+into the code, here is a guideline to set up your environment:
+
+### Virtual environment with `venv`
+
+You can create a virtual environment in a directory using Python's `venv`
+module:
+
+<div class="termy">
+
+```console
+python -m venv env
+```
+
+</div>
+
+That will create a directory `./env/` with the python binaries and then you will
+be able to install packages for that isolated environment.
+
+### Activate the environment
+
+Activate the new environment with:
+
+=== "Linux, macOS"
+
+    <div class="termy">
+
+    ```console
+    $ source ./env/bin/activate
+    ```
+
+    </div>
+
+=== "Windows PowerShell"
+
+    <div class="termy">
+
+    ```console
+    $ .\env\Scripts\Activate.ps1
+    ```
+
+    </div>
+
+=== "Windows Bash"
+
+    Or if you use Bash for Windows (e.g. <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>):
+
+    <div class="termy">
+
+    ```console
+    $ source ./env/Scripts/activate
+    ```
+
+    </div>
+
+To check it worked, use:
+
+=== "Linux, macOS, Windows Bash"
+
+    <div class="termy">
+
+    ```console
+    $ which pip
+    ```
+
+    </div>
+
+=== "Windows PowerShell"
+
+    <div class="termy">
+
+    ```console
+    $ Get-Command pip
+    ```
+
+    </div>
+
+If it shows the `pip` binary at `env/bin/pip` then it worked. 🎉
+
+!!! tip Every time you install a new package with `pip` under that environment,
+activate the environment again.
+
+    This makes sure that if you use a terminal program installed by that package (like `pre-commit`), you use the one from your local environment and not any other that could be installed globally.
+
+### Setup Flit
+
+Flit is a simple way to put Python packages and modules on PyPI. It tries to
+require less thought about packaging and help you avoid common mistakes.
+
+It’s easy to underestimate the challenges involved in distributing and
+installing code, because it seems like you just need to copy some files into the
+right place. There’s a whole lot of metadata and tooling that has to work
+together around that fundamental step. But with the right tooling, a developer
+who wants to release their code doesn’t need to know about most of that.
+
+<div class="termy">
+
+```console
+pip install flit
+```
+
+</div>
+
+### Development Dependencies
+
+Now lets install all the package that you need to develop Ormdantic:
+
+=== "Terminal"
+
+    <div class="termy">
+
+    ```console
+    $ flit install --symlink
+    ```
+    </div>
+
+It will install all the dependencies in your local environment.
+
+#### Including
+
+The Dependencies file contains all the dependencies that you need to develop
+Ormdantic, which are:
+
+- The Base Dependencies - the ones that are needed to run Ormdantic.
+  [See Installation](installation.md).
+
+### Format
+
+For Providing a good and consistent experience, we recommend using
+[pre-commit](https://pre-commit.com/) - a tool that runs a set of checks before
+you commit your code.
+
+#### Git Hooks
+
+First you need to install the [pre-commit](https://pre-commit.com/) tool, which
+is installed before with the Dev Dependencies.
+
+Now, install the pre-commit hooks in your `.git/hooks/` directory:
+
+<div class="termy">
+
+```console
+pre-commit install
+```
+
+</div>
+
+This one will provide a linting check before you commit your code.
+
+#### Including
+
+The `.pre-commit-config.yaml` contains the following configuration with the
+linting packages.
+
+- `pre-commit-hooks` - Some out-of-the-box hooks for pre-commit.
+- `isort` - A tool to sort imports.
+- `flake8` - A tool to check Python code for errors.
+- `mirrors-autoflake` - Mirror of the autoflake package for pre-commit.
+- `black` - A tool to format Python code.
+- `pyupgrade` - A tool to automatically upgrade syntax for newer versions of the language.
+
+## Documentation
+
+First, make sure you set up your environment as described above, that will
+install all the requirements.
+
+The documentation uses
+<a href="https://www.mkdocs.org/" class="external-link" target="_blank">MkDocs</a>.
+
+All the documentation is in Markdown format in the directory `./docs`.
+
+### Including
+
+To Build Ormdantic Documentation we need the following packages, which are:
+
+- `mkdocs` - The tool that builds the documentation.
+- `mkdocs-material` - The theme that Ormdantic uses.
+- `mkdocs-markdownextradata-plugin` - The plugin that allows to add extra data
+  to the documentation.
+
+### Translations
+
+Help with translations is VERY MUCH appreciated! And it can't be done without
+the help from the community. 🌎 🚀
+
+Here are the steps to help with translations.
+
+#### Tips and guideline
+
+- Check the currently
+  <a href="https://github.com/yezz123/Ormdantic/pulls" class="external-link" target="_blank">existing
+  pull requests</a> for your language and add reviews requesting changes or
+  approving them.
+
+!!! tip You can
+<a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request" class="external-link" target="_blank">add
+comments with change suggestions</a> to existing pull requests.
+
+    Check the docs about <a href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews" class="external-link" target="_blank">adding a pull request review</a> to approve it or request changes.
+
+- Check in the
+  <a href="https://github.com/yezz123/Ormdantic/issues" class="external-link" target="_blank">issues</a>
+  to see if there's one coordinating translations for your language.
+
+- Add a single pull request per page translated. That will make it much easier
+  for others to review it.
+
+For the languages I don't speak, I'll wait for several others to review the
+translation before merging.
+
+- You can also check if there are translations for your language and add a
+  review to them, that will help me know that the translation is correct and I
+  can merge it.
+
+- Use the same Python examples and only translate the text in the docs. You
+  don't have to change anything for this to work.
+
+- Use the same images, file names, and links. You don't have to change anything
+  for it to work.
+
+- To check the 2-letter code for the language you want to translate you can use
+  the table
+  <a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes" class="external-link" target="_blank">List
+  of ISO 639-1 codes</a>.
+
+## Testing
+
+all the dependencies that you need to test Ormdantic, which are:
+
+### Including
+
+- `pytest` - The tool that runs the tests.
+- `pytest-asyncio` - The plugin that runs the tests in the background.
+
+### Generate a Test Report
+
+As we know, the tests are very important to make sure that Ormdantic works as
+expected, that why i provide a multi test for and functions to provide a good
+test.
+
+If you want to generate the test report:
+
+<div class="termy">
+
+```console
+bash scripts/test_html.sh
+```
+
+</div>