Merge pull request #147 from ZeroIntensity/docs-rewrite

Docs Rewrite

.github/workflows/build.yml

@@ -32,7 +32,7 @@ jobs:
                   fetch-depth: 0
 
             - name: Build wheels
-              uses: pypa/cibuildwheel@v2.15.0
+              uses: pypa/cibuildwheel@v2.16.5
               env:
                   CIBW_ARCHS_MACOS: x86_64
                   HATCH_BUILD_HOOKS_ENABLE: "true"

CHANGELOG.md

@@ -5,106 +5,109 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Unreleased
-
-- Fixed `template` attribute with the `view` template renderer
-- Added the `context` decorator and the `Context` type
-- Added the `headers` parameter to functions on `TestingContext`
-- Modified some behavior of automatic route inputs
-- Fixed syntax errors in `view init`
-- Added `Route.middleware`
-- Routes with equivalent paths but different methods now return `405 Method Not Allowed` when accessed
-- Added `route` and `App.route`
-- Added docstrings to router functions
-- Added the `JSON` response class
-- Added the `custom` body translate strategy
-- Made `method` a keyword-only parameter in `path`
-- Added the `extract_path` utility
-- Added the `view build` command
-- Added `App.template`
-- Route errors now display the error message when `dev` is `True`
-- Changed exception rendering in route errors to use the `rich` renderer
-- Added `compile_type` and `TCValidator`
-- Added `markdown` and `App.markdown`
-- Added the `Error` class
-- Added the `error_class` parameter to both `new_app` and `App`
-- Added the `ERROR_CODES` constant
-- **Breaking Change:** The `body` parameter in `Response` is now required
+## [1.0.0-alpha9] - 2024-2-4
+
+-   Fixed `template` attribute with the `view` template renderer
+-   Added the `context` decorator and the `Context` type
+-   Added the `headers` parameter to functions on `TestingContext`
+-   Modified some behavior of automatic route inputs
+-   Fixed syntax errors in `view init`
+-   Added `Route.middleware`
+-   Routes with equivalent paths but different methods now return `405 Method Not Allowed` when accessed
+-   Added `route` and `App.route`
+-   Added docstrings to router functions
+-   Added the `JSON` response class
+-   Added the `custom` body translate strategy
+-   Made `method` a keyword-only parameter in `path`
+-   Added the `extract_path` utility
+-   Added the `view build` command
+-   Added `App.template`
+-   Route errors now display the error message when `dev` is `True`
+-   Changed exception rendering in route errors to use the `rich` renderer
+-   Added `compile_type` and `TCValidator`
+-   Added `markdown` and `App.markdown`
+-   Added the `Error` class
+-   Added the `error_class` parameter to both `new_app` and `App`
+-   Added the `ERROR_CODES` constant
+-   Completely rewrote docs
+-   **Breaking Change:** The `body` parameter in `Response` is now required
 
 ## [1.0.0-alpha8] - 2024-1-21
 
-- Added optional dependencies for `databases` and `templates`
-- Added environment prefixes for database configuration
-- Added `templates` and `TemplatesConfig` to config
-- Added the `templates` function
-- Added support for `attrs` in type validation
-- Added documentation for caching
-- Added the `cache_rate` parameter to routers
-- Removed `psutil` and `plotext` as a global dependency
-- Added `fancy` optional dependencies
-- Fixed route inputs with synchronous routes
-- **Breaking Change:** Route inputs are now applied in the order of the decorator call as it appears in code
+-   Added optional dependencies for `databases` and `templates`
+-   Added environment prefixes for database configuration
+-   Added `templates` and `TemplatesConfig` to config
+-   Added the `templates` function
+-   Added support for `attrs` in type validation
+-   Added documentation for caching
+-   Added the `cache_rate` parameter to routers
+-   Removed `psutil` and `plotext` as a global dependency
+-   Added `fancy` optional dependencies
+-   Fixed route inputs with synchronous routes
+-   **Breaking Change:** Route inputs are now applied in the order of the decorator call as it appears in code
 
 ## [1.0.0-alpha7] - 2023-12-7
 
 **Quick Patch Release**
 
-- Remerged new `view init` command.
+-   Remerged new `view init` command.
 
 ## [1.0.0-alpha6] - 2023-11-30
 
-- Added `get_app`
-- Added documentation generation
-- Added database support (NOT FINISHED)
-- Removed `attempt_import` and `MissingLibraryError`
-- Added support for lists in type validation
-- Added support for implicit query parameters
-- Renamed `debug` to `enable_debug`
-- Added `debug`, `info`, `warning`, `error`, and `critical` logging functions
-- Added `InvalidRouteError`, `DuplicateRouteError`, `ViewInternalError`, and `ConfigurationError`
-- Renamed `EnvironmentError` to `BadEnvironmentError`
-- Added logging functions to `App`
-- Changed environment prefixes for configuration
-- Rewrote documentation
-- Added `patterns` loader
-- Added handling of relative paths in the configuration setting `loader_path`
-- Added exists validation to `loader_path`
-- Add path to `PATH` environment variable during loading
-- Upgraded `view init`
+-   Added `get_app`
+-   Added documentation generation
+-   Added database support (NOT FINISHED)
+-   Removed `attempt_import` and `MissingLibraryError`
+-   Added support for lists in type validation
+-   Added support for implicit query parameters
+-   Renamed `debug` to `enable_debug`
+-   Added `debug`, `info`, `warning`, `error`, and `critical` logging functions
+-   Added `InvalidRouteError`, `DuplicateRouteError`, `ViewInternalError`, and `ConfigurationError`
+-   Renamed `EnvironmentError` to `BadEnvironmentError`
+-   Added logging functions to `App`
+-   Changed environment prefixes for configuration
+-   Rewrote documentation
+-   Added `patterns` loader
+-   Added handling of relative paths in the configuration setting `loader_path`
+-   Added exists validation to `loader_path`
+-   Add path to `PATH` environment variable during loading
+-   Upgraded `view init`
 
 ## [1.0.0-alpha5] - 2023-09-24
 
-- Added `app.query` and `app.body`
-- Patched warning with starting app from incorrect filename
-- Updated `__all__` for `routing.py`
-- Added `view.Response` and `view.HTML`
-- Fixed `__view_result__`
-- Added support for `__view_body__` and `__view_construct__`
-- Added support for Pydantic, `NamedTuple`, and dataclasses for type validation
-- Support for direct union types (i.e. `str | int`, `Union[str, int]`) on type validation
-- Added support for non async routes
+-   Added `app.query` and `app.body`
+-   Patched warning with starting app from incorrect filename
+-   Updated `__all__` for `routing.py`
+-   Added `view.Response` and `view.HTML`
+-   Fixed `__view_result__`
+-   Added support for `__view_body__` and `__view_construct__`
+-   Added support for Pydantic, `NamedTuple`, and dataclasses for type validation
+-   Support for direct union types (i.e. `str | int`, `Union[str, int]`) on type validation
+-   Added support for non async routes
 
 ## [1.0.0-alpha4] - 2023-09-10
-- Added type validation (without support for `__view_body__`)
-- Patched query strings on app testing
-- Added tests for query and body parameters
-- Patched body parameters
-- Documented type validation
-- Patched bodies with testing
+
+-   Added type validation (without support for `__view_body__`)
+-   Patched query strings on app testing
+-   Added tests for query and body parameters
+-   Patched body parameters
+-   Documented type validation
+-   Patched bodies with testing
 
 ## [1.0.0-alpha3] - 2023-09-9
-- Patched header responses
-- Added tests for headers
-- Updated repr for `Route`
-- Patched responses with three values
-- Documented responses and result protocol
+
+-   Patched header responses
+-   Added tests for headers
+-   Updated repr for `Route`
+-   Patched responses with three values
+-   Documented responses and result protocol
 
 ## [1.0.0-alpha2] - 2023-09-9
 
-- Added `App.test()`
-- Added warning when filename does not match `app_path`
-- Added more tests
-- Upgrade CIBW to work on 3.11
+-   Added `App.test()`
+-   Added warning when filename does not match `app_path`
+-   Added more tests
+-   Upgrade CIBW to work on 3.11
 
 ## [1.0.0-alpha1] - 2023-08-17
 

docs/building-projects/app_basics.md

@@ -8,26 +8,27 @@ Every view project will have a `new_app` call. The simplest app looks like this:
 from view import new_app
 
 app = new_app()
+app.run()  # you'll learn about this later
 ```
 
 `new_app` does a few important things:
 
-- Loads the configuration, regardless of whether a config file exists.
-- Sets the `App` address for use by `get_app` (more on that later).
-- Loads finalization code for when the app closes.
+-   Loads the configuration, regardless of whether a config file exists.
+-   Sets the `App` address for use by `get_app` (more on that later).
+-   Loads finalization code for when the app closes.
 
 While it's not required for every app, naming your app variable `app` is the proper convention for view, as that's the default variable searched for when using the `view serve` command, but more on that in a moment.
 
 For now, just try to stick with naming your app file `app.py` and your `view.App` instance `app`.
 
-::: view.app.App
+::: view.app.new_app
 
 ## Launching Apps
 
 Python libraries generally have two ways to run a web server:
 
-- Running via the command line.
-- Launching from Python itself (e.g. a `server.start(...)` function).
+-   Running via the command line.
+-   Launching from Python itself (e.g. a `server.start(...)` function).
 
 Both have their benefits and downsides, so view.py supports both out of the box. `App` comes with its `run()` method, and the view CLI has the `view serve` command.
 
@@ -54,17 +55,17 @@ app.run()
 print("you called the app with view serve")  # this only runs when `view serve` is used
 ```
 
-::: view.app.App.run
-
 ### Fancy Mode
 
 View comes with something called "fancy mode", which is a fancy UI that shows when you run the app. If you would like to disable this, you can do one of two things:
 
-- Disable the `fancy` setting in configuration.
-- Pass `fancy=False` to `run()`.
+-   Disable the `fancy` setting in configuration.
+-   Pass `fancy=False` to `run()`.
 
 You should disable it in the configuration if you completely despise fancy mode and don't want to use it at all, but if you only want to temporarily turn it off (for example, if you're a view.py developer and need to see proper output) then pass `fancy=False`.
 
+::: view.app.App.run
+
 ## Getting the App
 
 ### Circular Imports
@@ -117,6 +118,6 @@ def index():
 
 Every view.py project should contain a call to `new_app`. `new_app` does important things like loading your configuration, set's up finalization code, and letting the `App` instance be used by `get_app`.
 
-Running an app can be done in two ways: programmatically via the `App.run` or through `view serve` command. However, every view.py app should contain an `App.run` to give the choice for running programmatically. By default, view.py has a fancy UI when running your app, which may be disabled via editing the config or passing `fancy=False` to `run()`. 
+Running an app can be done in two ways: programmatically via the `App.run` or through `view serve` command. However, every view.py app should contain an `App.run` to give the choice for running programmatically. By default, view.py has a fancy UI when running your app, which may be disabled via editing the config or passing `fancy=False` to `run()`.
 
 Finally, circular imports occur when two Python modules try to import each other, which can happen a lot in view when getting the app from the app file (especially in manual routing). To fix it, View provides a `get_app` function to get you your `App` instance without an import.