Merge pull request #61 from findsimilar/autodocs

Autodocs

.github/workflows/static.yml → .github/workflows/docs.yml

@@ -2,9 +2,8 @@
 name: Deploy Documentation to GitHub pages
 
 on:
-  # Runs on pushes targeting the default branch
-  push:
-    branches: ["main"]
+  release:
+    types: [published]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -15,8 +14,10 @@ permissions:
   pages: write
   id-token: write
 
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+# Allow only one concurrent deployment,
+# skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow
+# these production deployments to complete.
 concurrency:
   group: "pages"
   cancel-in-progress: false
@@ -39,17 +40,19 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install -r requirements.txt
-          pip install pdoc
+          pip install -r doc-requirements.txt
       - name: Build documentation
         run: |
-          make docs
+          make package_docs
+          cd docs
+          make html
       - name: Setup Pages
         uses: actions/configure-pages@v3
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v2
         with:
           # Upload entire repository
-          path: './.docs'
+          path: './docs/_build/html'
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v2

.github/workflows/pypi-publish.yml

@@ -1,17 +1,12 @@
-# This workflow will upload a Python Package using Twine when a release is created
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
-
-# This workflow uses actions that are not certified by GitHub.
-# They are provided by a third-party and are governed by
-# separate terms of service, privacy policy, and support
-# documentation.
-
 name: Upload Python Package To pypi
 
 on:
   release:
     types: [published]
 
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
 permissions:
   contents: read
 

.github/workflows/run-tests.yml

@@ -1,6 +1,3 @@
-# This workflow will install Python dependencies, run tests and lint with a single version of Python
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
-
 name: Run Tests
 
 on: [push, pull_request]
@@ -14,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11"]
+        python-version: ["3.10", "3.11", '3.12']
     steps:
     - uses: actions/checkout@v3
     - name: Set up Python ${{ matrix.python-version }}

CHECKLIST.md

@@ -19,7 +19,7 @@
 - [x] [Documentation](https://github.com/quillcraftsman/open-source-checklist#documentation)
 - [x] [Developer Documentation](https://github.com/quillcraftsman/open-source-checklist#developer-documentation)
 - [x] [Availability of Documentation](https://github.com/quillcraftsman/open-source-checklist#availability-of-documentation)
-- [ ] [FAQ](https://github.com/quillcraftsman/open-source-checklist#faq)
+- [x] [FAQ](https://github.com/quillcraftsman/open-source-checklist#faq)
 - [x] [Examples Output and Screenshots](https://github.com/quillcraftsman/open-source-checklist#examples-output-and-screenshots)
 - [x] [License](https://github.com/quillcraftsman/open-source-checklist#license)
 - [x] [Code of Conduct](https://github.com/quillcraftsman/open-source-checklist#code-of-conduct)

CODE_OF_CONDUCT.md

@@ -1,60 +1,3 @@
 # Code of Conduct
 
-## Our Pledge
-
-In the interest of fostering an open and welcoming environment, 
-we as contributors and maintainers pledge to make 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:
-
-- 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 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.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team 
-at [[email protected]](mailto:[email protected]). 
-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](https://www.contributor-covenant.org), 
-version 1.4, available 
-at [https://www.contributor-covenant.org/version/1/4/code-of-conduct.html](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html)
-
-For answers to common questions about this code of conduct, 
-see [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq)
+FindSimilar [Code Of Conduct](https://github.com/findsimilar/community/blob/main/CODE_OF_CONDUCT.md)

CONTRIBUTING.md

@@ -1,35 +1,41 @@
-# Developer Guidelines
+# Guidance on how to contribute
 
-## How to report an issue
+There are many ways to help:
+- [Using GitHub stars and discussions](#using-github-start-and-discussions)
+- [Using the issue tracker](#using-the-issue-tracker)
+- [Changing the code-base](#changing-the-code-base)
 
-* You can find all the project issue on GitHub [here](https://github.com/findsimilar/find-similar/issues)
-* If you found a bug, you can [create new issue](https://github.com/findsimilar/find-similar/issues/new) with the bug label
+## Using GitHub stars and discussions
 
-## How to write a code
+The most simple way to help the project - Press the **Star** button if you like the project.
 
-First you can check [existing issues](https://github.com/findsimilar/find-similar/issues). Pick one or create your own.
+Your participation in [discussions][discussions-path] will also be useful.
 
-* Create "Fork" of the project
-* To run the project and tests see [Developer documentation](https://github.com/findsimilar/find-similar/blob/master/DEVELOPER_DOCUMENTATION.md)
-* Do some changes locally
-* Create pull request to this repository (you can use git or "Contribute" button at the top of your local repository)
+Press the **Eye** button to watch for changes.
 
-## How development is usually done
+## Using the issue tracker
 
-The most involved people are the [members of organization](https://github.com/orgs/findsimilar/people). 
-They can make code review and accept pull requests.
-But any person can be involved report a bug of release a patch.
-We are always open to new people.
-New most involved contributors can become members of the organization
+Use the [issue tracker][issues-path]
+to suggest feature requests, report bugs, and ask questions.
+This is also a great way to connect with the developers of the project as well
+as others who are interested in this solution.
 
-## Interaction with other developers
+Use the [issue tracker][issues-path]  to find ways to contribute. 
+Find a bug or a feature, mention in
+the issue that you will take on that effort, then follow the _Changing the code-base_
+guidance below.
 
-Now we use issues and comments in pull requests.
+## Changing the code-base
 
-If you need something else like:
-* forum 
-* or realtime chat 
-* mail list
-* of discussions on GitHub
+Generally speaking, you should **fork** this repository, make changes in your
+own fork, and then submit a **pull request**. All new code should have associated
+unit tests that validate implemented features and the presence or lack of defects.
+Additionally, the code should follow any stylistic and architectural guidelines
+prescribed by the project. In the absence of such guidelines, mimic the styles
+and patterns in the existing code-base.
 
-Mail to [[email protected]](mailto:[email protected]) and we will discuss this. 
+You can check [Developer Documentation][developer-documentation-path] to easy start with code
+
+[issues-path]: https://github.com/findsimilar/find-similar/issues
+[discussions-path]: https://github.com/findsimilar/find-similar/discussions
+[developer-documentation-path]: https://docs.findsimilar.org/dev_documentation.html

GOVERNANCE.md

@@ -0,0 +1,3 @@
+# Governance
+
+FindSimilar [Governance](https://github.com/findsimilar/community/blob/main/GOVERNANCE.md)

Makefile

@@ -4,9 +4,6 @@ test:
 coverage:
 	pytest -s --cov --cov-report html --cov-fail-under 97
 
-docs:
-	pdoc ./find_similar/ -o ./.docs
-
 yamllint:
 	yamllint -d relaxed .
 
@@ -30,4 +27,10 @@ pylint:
 
 lint:
 	make yamllint
-	make pylint
+	make pylint
+
+sphinx-help:
+	make help -f Sphinxfile
+
+package_docs:
+	sphinx-apidoc -o docs/package find_similar/