Attempt to fix docs (#303)

yuval9313 · web-flow · commit bf9c21503259 · 2024-05-11T19:58:32.000+03:00
* Attempt to fix docs

* Fix typo in docs

* Fix another typo

* Update docs so nav would work properly
diff --git a/.gitignore b/.gitignore
@@ -7,11 +7,6 @@ venv/
 .venv/
 env3*/
 
-# Repo files that copied into docs
-docs/index.md
-docs/release-notes.md
-docs/contributing.md
-
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -0,0 +1,135 @@
+First, you might want to see the basic ways to [help and get help](help-fastapi-utils.md){.internal-link target=_blank}.
+
+## Developing
+
+Once you've cloned the repository, here are some guidelines to set up your environment:
+
+### Set up the development evironment
+
+After cloning the repository, you can use `poetry` to create a virtual environment: 
+
+```console
+$ make develop
+```
+
+Behind the scenes, this checks that you have python3 and poetry installed,
+then creates a virtual environment and installs the dependencies. At the end, it will print out
+the path to the executable in case you want to add it to your IDE.
+
+
+### Activate the environment
+
+Once the virtual environment is created, you can activate it with:
+
+```console
+$ poetry shell
+```
+
+To check if this worked, try running: 
+
+```console
+$ which python
+
+some/directory/fastapi-utils-SOMETHING-py3.X/bin/python
+```
+
+If the output of this command shows the `python` binary in a path containing `fastapi-utils` somewhere in the name
+(as above), 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 `mypy`),
+    you use the one from your local environment and not any other that could be installed globally.
+
+### Static Code Checks
+
+This project makes use of `black`, `autoflake8`, and `isort` for formatting,
+`flake8` for linting, and `mypy` for static type checking.
+
+
+To auto-format your code, just run:
+
+```console
+$ make format
+```
+
+It will also auto-sort all your imports, and attempt to remove any unused imports.
+
+You can run flake8 with:
+
+```console
+$ make lint
+```
+
+and you can run mypy with:
+
+```console
+$ make mypy
+```
+
+There are a number of other useful makefile recipes; you can see basic documentation of these by calling plain `make`:
+
+```console
+$ make
+```
+
+
+## Docs
+
+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`.
+
+Many of the sections in the User Guide have blocks of code.
+
+In fact, those blocks of code are not written inside the Markdown, they are Python files in the `./docs/src/` directory.
+
+And those Python files are included/injected in the documentation when generating the site.
+
+### Docs for tests
+
+Most of the tests actually run against the example source files in the documentation.
+
+This helps making sure that:
+
+* The documentation is up to date.
+* The documentation examples can be run as is.
+* Most of the features are covered by the documentation, ensured by test coverage.
+
+During local development, there is a script that builds the site and checks for any changes, live-reloading:
+
+```console
+$ bash scripts/docs-live.sh
+```
+
+It will serve the documentation on `http://0.0.0.0:8008`.
+
+That way, you can edit the documentation/source files and see the changes live.
+
+## Tests
+
+You can run all tests via:
+
+```console
+$ make test
+```
+
+You can also generate a coverage report with:
+
+```console
+make testcov
+```
+
+On MacOS, if the tests all pass, the coverage report will be opened directly in a browser; on other operating systems
+a link will be printed to the local HTML containing the coverage report.
+
+### Tests in your editor
+
+If you want to use the integrated tests in your editor add `./docs/src` to your `PYTHONPATH` variable.
+
+For example, in VS Code you can create a file `.env` with:
+
+```env
+PYTHONPATH=./docs/src
+```
diff --git a/docs/help-fastapi-utils.md b/docs/help-fastapi-utils.md
@@ -31,7 +31,7 @@ You can connect with the maintainer on
 
 ## Create issues
 
-You can <a href="https://github.com/dmontagu/fastapis-utils/issues/new/choose" class="external-link" target="_blank">create a new issue</a> in the GitHub repository, for example to:
+You can <a href="https://github.com/dmontagu/fastapi-utils/issues/new/choose" class="external-link" target="_blank">create a new issue</a> in the GitHub repository, for example to:
 
 * Report a bug/issue.
 * Suggest a new feature.
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,74 @@
+<p align="center">
+    <em>Quicker FastApi developing tools</em>
+</p>
+<p align="center">
+<a href="https://github.com/dmontagu/fastapi-utils" target="_blank">
+	<img src="https://img.shields.io/github/last-commit/dmontagu/fastapi-utils.svg">
+	<img src="https://github.com/dmontagu/fastapi-utils/workflows/build/badge.svg" alt="Build CI">
+</a>
+<a href="https://codecov.io/gh/dmontagu/fastapi-utils" target="_blank">
+    <img src="https://codecov.io/gh/dmontagu/fastapi-utils/branch/master/graph/badge.svg" alt="Coverage">
+</a>
+<br />
+<a href="https://pypi.org/project/fastapi-utils" target="_blank">
+    <img src="https://badge.fury.io/py/fastapi-utils.svg" alt="Package version">
+</a>
+<a href="https://github.com/dmontagu/fastapi-utils" target="_blank">
+    <img src="https://img.shields.io/pypi/pyversions/fastapi-utils.svg" alt="Python versions">
+    <img src="https://img.shields.io/github/license/dmontagu/fastapi-utils.svg" alt="License">
+</a>
+</p>
+
+---
+**Documentation**: <a href="https://fastapi-utils.davidmontague.xyz" target="_blank">https://fastapi-utils.davidmontague.xyz</a>
+
+**Source Code**: <a href="https://github.com/dmontagu/fastapi-utils" target="_blank">https://github.com/dmontagu/fastapi-utils</a>
+
+---
+
+<a href="https://fastapi.tiangolo.com">FastAPI</a> is a modern, fast web framework for building APIs with Python 3.7+.
+
+But if you're here, you probably already knew that!
+
+---
+
+## Features
+
+This package includes a number of utilities to help reduce boilerplate and reuse common functionality across projects:
+
+* **Resource Class**: Create CRUD with ease the OOP way with `Resource` base class that lets you implement methods quick.
+* **Class Based Views**: Stop repeating the same dependencies over and over in the signature of related endpoints.
+* **Repeated Tasks**: Easily trigger periodic tasks on server startup
+* **Timing Middleware**: Log basic timing information for every request
+* **OpenAPI Spec Simplification**: Simplify your OpenAPI Operation IDs for cleaner output from OpenAPI Generator
+* **SQLAlchemy Sessions**: The `FastAPISessionMaker` class provides an easily-customized SQLAlchemy Session dependency
+
+---
+
+It also adds a variety of more basic utilities that are useful across a wide variety of projects:
+
+* **APIModel**: A reusable `pydantic.BaseModel`-derived base class with useful defaults
+* **APISettings**: A subclass of `pydantic.BaseSettings` that makes it easy to configure FastAPI through environment variables
+* **String-Valued Enums**: The `StrEnum` and `CamelStrEnum` classes make string-valued enums easier to maintain
+* **CamelCase Conversions**: Convenience functions for converting strings from `snake_case` to `camelCase` or `PascalCase` and back
+* **GUID Type**: The provided GUID type makes it easy to use UUIDs as the primary keys for your database tables
+
+See the [docs](https://https://fastapi-utils.davidmontague.xyz/) for more details and examples.
+
+## Requirements
+
+This package is intended for use with any recent version of FastAPI (depending on `pydantic>=1.0`), and Python 3.7+.
+
+## Installation
+
+```bash
+pip install fastapi-restful  # For basic slim package :)
+
+pip install fastapi-restful[session]  # To add sqlalchemy session maker
+
+pip install fastapi-restful[all]  # For all the packages
+```
+
+## License
+
+This project is licensed under the terms of the MIT license.
diff --git a/docs/release-notes.md b/docs/release-notes.md
@@ -0,0 +1,95 @@
+## Latest changes
+
+* Merge with [fastapi-utils](https://github.com/dmontagu/fastapi-utils)
+
+## 0.6.0
+
+* Fix bug where `Request.url_for` is not working as intended [[yuval9313/FastApi-RESTful#90](https://github.com/yuval9313/FastApi-RESTful/issues/90)]
+* Update multiple dependencies using @dependebot
+* Fix `repeat_every` is only running once [#142](https://github.com/yuval9313/FastApi-RESTful/pull/142)
+
+## 0.5.0
+
+* Bump sqlalchemy from 1.4.48 to 2.0.19 by @dependabot in #202
+* Pydantic v2 by @ollz272 in [#199](https://github.com/yuval9313/FastApi-RESTful/pull/199)
+* fix ci not run by @ollz272 in [#208](https://github.com/yuval9313/FastApi-RESTful/pull/208)
+
+## 0.4.5
+
+* Change the lock of fastapi to enable more versions of it to be installed
+
+## 0.4.4
+
+* Move to ruff for linting, etc.
+* Update various dependencies
+* Stop supporting Python 3.6
+* Deprecate InferringRouter (as its functionality is now built into `fastapi.APIRouter`)
+* Resolve various deprecationwarnings introduced by sqlalchemy 1.4.
+* Add support to Python 3.11
+* Change package description to avoid errors with pypi as [mentioned here](https://github.com/yuval9313/FastApi-RESTful/issues/175)
+
+## 0.4.3
+
+* Fix bug where inferred router raises exception when no content is needed but type hint is provided (e.g. `None` as return type with status code 204) (As mentiond in [#134](https://github.com/yuval9313/FastApi-RESTful/pull/134))
+* Improve tests and add more test cases
+* Bump dependencies versions
+
+## 0.4.2
+
+* Remove version pinning to allow diversity in python environments
+
+## 0.4.1
+
+* Add more pypi classifiers
+
+## 0.4.0
+
+** Breaking change **
+* Remove support to python < 3.6.2
+
+Additionals:
+* Multiple version bumps
+* Add usage of **kwargs for to allow more options when including new router
+
+## 0.3.1
+
+* [CVE-2021-29510](https://github.com/samuelcolvin/pydantic/security/advisories/GHSA-5jqp-qgf6-3pvh) fix of pydantic - update is required
+* Made sqlalchemy as extras installs 
+
+## 0.3.0
+
+* Add support for Python 3.9 :)
+* Fix case of duplicate routes when cbv used with prefix. (As mentioned in [#36](https://github.com/yuval9313/FastApi-RESTful/pull/36))
+* Made repeatable task pre activate (`wait_first`) to be float instead of boolean (Mentioned here [#45](https://github.com/yuval9313/FastApi-RESTful/pull/45)) 
+
+## 0.2.4.1
+
+* Another docs fix
+* Rename package folder to small casing to ease imports
+
+## 0.2.4
+
+* Mostly docs fixes
+
+## 0.2.2
+
+* Add `Resorce` classes for more OOP like designing
+* Methods are now can be used as class names
+
+## 0.2.1
+
+* Fix bug with multiple decorators on same method 
+
+## 0.2.0
+
+* Make some of the functions/classes in `fastapi_utils.timing` private to clarify the intended public API
+* Add documentation for `fastapi_utils.timing` module 
+* Fix bug with ordering of routes in a CBV router 
+
+## 0.1.1
+
+* Add source docstrings for most functions.
+
+## 0.1.0
+
+* Initial release.
diff --git a/docs/user-guide/basics/enums.md b/docs/user-guide/basics/enums.md
@@ -25,7 +25,7 @@ class MyEnum(str, Enum):
 One nuisance with this approach is that if you rename one of the enum values (for example, using an IDE),
 you can end up with the name and value differing, which may lead to confusing errors.
 
-For example, if you refactored the above as follows (forgetting to çhange the associated values), you'll get
+For example, if you refactored the above as follows (forgetting to change the associated values), you'll get
 pydantic parsing errors if you use the new *names* instead of the values in JSON bodies:  
 
 ```python
diff --git a/docs/user-guide/class-based-views.md b/docs/user-guide/class-based-views.md
@@ -48,9 +48,6 @@ The highlighted lines above show the results of performing each of the numbered
 Note how the signature of each endpoint definition now includes only the parts specific
 to that endpoint. 
 
-(Also note that we've also used the [`InferringRouter`](inferring-router.md){.internal-link target=_blank}
-here to remove the need to specify a `response_model` in the endpoint decorators.)
-
 Hopefully this helps you to better reuse dependencies across endpoints!
 
 !!! info
