Merge pull request #593 from render-engine/convert-docs-markdown

docs: convert to markdown and fix paths

docs/docs/archive.md

@@ -1,11 +1,31 @@
 <!-- markdownlint-disable MD052 -->
 # Archive
 
-Archives are a [`BasePage`][src.render_engine.page.BasePage] object used to display a list of [`Page`][src.render_engine.page.Page] objects in a [`Collection`][src.render_engine.collection.Collection].
+Archives are a [`BasePage`](./page?id=basepage) object used to display a list of [`Page`](./page?id=page) objects in a [`Collection`](./collection?id=collection).
 
 Archive objects create a customizable page that can be controlled via its parent Collection.
 
-::: src.render_engine.archive.Archive
+Bases: [`BasePage`](./page?id=basepage)
+
+The Archive is a [Page](./page?id=page) object used by the collection
+that focuses on presenting the Collection's pages.
+
+**Parameters:**
+
+| Name | Type | Description | Default |
+| --- | --- | --- | --- |
+| `pages` | `list[`[`BasePage`](./page?id=basepage)`]` |The list of pages to include in the archive | _required_ |
+| `title` | `str` |The title of the archive | _required_ |
+| `template` | `str \| Template` |The template to use for the archive | _required_ |
+| `routes` | `list[str \|Path]` |The routes for where the archive page should be generated | _required_ |
+| `archive_index` | `int` |The index of the page in the series of archive pages | `0` |
+| `num_of_pages` |  |The total number of pages in the series of archive pages | _required_ |
+
+>[!WARNING] Not Directly Used
+>
+> The Archive object is not meant to be used directly.
+> It is used by the [Collection](./collection?id=collection) object.
+> Attributes can be used to customize.
 
 Collection.archives yields a generator of Archive objects. Each Archive object will have a `pages` attribute that is a list of Page objects referenced in that Archive Page. The number of pages is determined by the `Collection.items_per_page` attribute.
 

docs/docs/cli.md

@@ -10,51 +10,61 @@ This allows you to quickly create or augment your render-engine site using a pre
 
 The default is the [cookiecutter-render-engine-site](https://github.com/render-engine/cookiecutter-render-engine-site).
 
-::: src.render_engine.cli.cli.init
+Create a new site configuration. You can provide extra_context to the cookiecutter template.
+
+Also any argument that cookiecutter accepts can be passed to this command.
+
+The template can be a local path or a git repository.
 
 ### `collection-path` (`Path`: default=`"pages"`)
 
-The path to the folder that will contain your [collections](../collection). This is where you will put your data files to be processed.
+The path to the folder that will contain your [collections](./collection). This is where you will put your data files to be processed.
 
 ### `force` (`bool`: default=`False` as `no-force`)
 
 Overwrite existing files and folders. If `no-force`, an error will be raised if **ANY** of the files already exist.
 
 ### `output-path` (`Path`: default=`"output"`)
 
-The path to the [`output`](../../site#output_path) directory. This is where your rendered site will be served.
+The path to the [`output`](./site?id=output_path) directory. This is where your rendered site will be served.
 
 ### `project-path-name` (`Path`: default=`"app.py"`)
 
-The name of the python file that will contain the Render Engine setup. This is where you will define your [site](../../site), [pages](../../page) and [collections](../../collection).
+The name of the python file that will contain the Render Engine setup. This is where you will define your [site](./site), [pages](./page) and [collections](./collection).
 
 ### `project-folder` (`Path`: default=`"."`)
 
 The name of the folder that will contain your project. This is where your [`project-path-name`](#project-path-name-path-defaultapppy), [`output-path`](#output-path-path-defaultoutput), [`templates-path`](#templates-path-path-defaulttemplates), and [`collection-path`](#collection-path-path-defaultpages) will be created.
 
 #### `site-description` (`str|None`: default=`None`)
 
-A short description of your site.  This will be passed into the [`Site`](../site.md) object and available in [`site_vars`](../site.md#site_vars).
+A short description of your site.  This will be passed into the [`Site`](./site) object and available in [`site_vars`](./site?id=site_vars).
 
 #### `site-author` - (`str|None` default: `None`)
 
-The author of the site.  This will be passed into the [`Site`](../site.md) object and available in [`site_vars`](../site.md#site_vars).
+The author of the site.  This will be passed into the [`Site`](./site) object and available in [`site_vars`](./site?id=site_vars).
 
 #### `skip-collection` (`bool`: default=`False` as `no-skip-collection`)
 
-If `True`, a [`collection-path`](../collection#content_path) folder will not be created.
+If `True`, a [`collection-path`](./collection?id=content_path) folder will not be created.
 
 #### `skip-static` - (`bool`: default: `False` as `no-skip-static`)
 
-If `True`, will not create the [`static`](../../site#static_path) folder. This is where you will put your static files (images, css, js, etc).
+If `True`, will not create the [`static`](./site?id=static_path) folder. This is where you will put your static files (images, css, js, etc).
 
 #### `templates-path` (`Path`: default=`"templates"`)
 
-The path to the folder that will contain your [`templates`](../templates). This is where you will put your Jinja2 templates.
+The path to the folder that will contain your [`templates`](./templates). This is where you will put your Jinja2 templates.
 
 ## Building your site with `render-engine build`
 
-::: src.render_engine.cli.cli.build
+CLI for creating a new site
+
+**Parameters:**
+
+| Name | Type | Description | Default |
+| --- | --- | --- | --- |
+|`module_site`|`Annotated[str, Argument(callback=split_module_site, help='module:site for Build the site prior to serving')]`|Python module and initialize Site class|_required_|
 
 `build` requires a `module_site` parameter in the format of `module:site`. `module` is the name of the python file that contains the `site` variable you've initialized. If the site `site` variable is in the `app.py` file, then the `module_site` parameter would be `app:site`.
 
@@ -66,7 +76,19 @@ The `serve` command creates a simple webserver that you can use to view your fil
 
 You can also use the `--reload` flag to have the site rebuild when changes are made.
 
-:::src.render_engine.cli.cli.serve
+Create an HTTP server to serve the site at `localhost`.
+
+> [!WARNING]
+> This is only for development purposes and should not be used in production.
+
+| Name | Type | Description | Default |
+| --- | --- | --- | --- |
+| `module_site` | `Annotated[str, Argument(callback=split_module_site, help='module:site for Build the site prior to serving')]` |Python module and initialize Site class | _required_ |
+| `reload` | `Annotated[bool, Option(--reload, -r, help='Reload the server when files change')]` |Use to reload server on file change | `None` |
+| `build` |  |flag to build the site prior to serving the app | _required_ |
+| `directory` | `Annotated[str, Option(--directory, -d, help='Directory to serve', show_default=False)]` |Directory to serve. If `module_site`is provided, this will be the `output_path`of the site. | `None` |
+| `port` | `Annotated[int, Option(--port, -p, help='Port to serve on', show_default=False)]` |Port to serve on | `8000` |
 
-!!! Note
-    `--reload` triggers a rebuild after re-importing the site object. Certain changes will not be picked up in the rebuild and reload.
+> [!NOTE]
+>
+> `--reload` triggers a rebuild after re-importing the site object. Certain changes will not be picked up in the rebuild and reload.

docs/docs/collection.md

@@ -1,7 +1,65 @@
-<!-- markdownlint-disable MD041 -->
-::: src.render_engine.collection.Collection
+# Collection
 
-# Passing Collection Variables to a Rendered Page
+Bases: `BaseObject`
+
+Collection objects serve as a way to quickly process pages that have a portion of content that is similar or file driven.
+
+Example:
+
+```Python
+from render_engine import Site, Collection
+
+site = Site()
+
+@site.collection
+class BasicCollection(Collection):
+    content_path = "content/pages"
+```
+
+Collection pages **MUST** come from a `content_path` and all be the same content type.
+
+`content_path` can be a string representing a path or URL, depending on the [parser](./parsers?id=basepageparser) used.
+
+Attributes:
+
+```Python
+archive_template: The template to use for the Archive pages.
+content_path: The path to iterate over to generate pages.
+content_type: Type[Page] = Page
+Feed: Type[RSSFeed]
+feed_title: str
+include_suffixes: list[str] = ["*.md", "*.html"]
+items_per_page: int | None
+Parser: BasePageParser = BasePageParser
+parser_extras: dict[str, Any]
+required_themes: list[callable]
+routes: list[str] = ["./"]
+sort_by: str = "title"
+sort_reverse: bool = False
+title: str
+template: str | None
+archive_template str | None: The template to use for the archive pages.
+```
+
+## Attributes
+
+`archives: typing.Generator[Archive, None, None]` `property`
+
+Returns a [Archive](./archive) objects containing the pages from the `content_path`.
+
+Archives are an iterable and the individual pages are built shortly after the collection pages are built. This happens when [Site.render](./site?id=render) is called.
+
+## Functions
+
+`get_page(content_path=None)`
+
+Returns the [page](./page) Object for the specified Content Path
+
+`iter_content_path()`
+
+Iterate through in the collection's content path.
+
+## Passing Collection Variables to a Rendered Page
 
 You can access attributes from the `Collection` class inside all of its rendered pages.
 

docs/docs/feeds.md

@@ -1 +1,32 @@
-::: src.render_engine.feeds
+# RSS Feed
+
+Feed Objects for Generating RSS Feeds
+
+## Classes
+
+`RSSFeed`
+
+Bases: [`BasePage`](./page?id=basepage)
+
+Creates an RSS feed [Page](./page) Object.
+
+> [!NOTE]
+> This is the base object type and should only contain the params identified by the standards defined in the [RSS 2.0 Specification](http://www.rssboard.org/rss-specification).
+
+This is built using the built-in `rss2.0.xml` jinja template.
+
+> [!NOTE]
+> Some browsers may not support the `rss` extension. If you are having issues with your feed, try changing the extension to `xml`.
+>
+> ```Python
+> from render_engine import Site, RSSFeed
+>
+> class MyFeed(RSSFeed):
+>    extension = "xml"
+>
+> site = Site()
+>
+> @site.collection
+> class MyCollection(Collection):
+>    Feed = MyFeed
+> ```

docs/docs/hookspecs.md

@@ -1 +1,45 @@
-:::src.render_engine.plugins
+# Hookspecs
+
+## Classes
+
+### `PluginManager`
+
+#### Functions
+
+##### `REGISTER_PLUGIN(PLUGIN)`
+
+Register a plugin with the site
+
+### `SiteSpecs`
+
+Plugin hook specifications for the Site class
+
+#### Functions
+
+##### `ADD_DEFAULT_SETTINGS(SITE)`
+
+Add default settings to the site
+
+##### `POST_BUILD_COLLECTION(SITE, SETTINGS)`
+
+Build After Building the collection
+
+##### `POST_BUILD_SITE(SITE)`
+
+Build After Building the site
+
+##### `POST_RENDER_CONTENT(PAGE, SETTINGS, SITE)`
+
+Augments the content of the page before it is rendered as output.
+
+##### `PRE_BUILD_COLLECTION(COLLECTION, SETTINGS)`
+
+Steps Prior to Building the collection
+
+##### `PRE_BUILD_SITE(SITE, SETTINGS)`
+
+Steps Prior to Building the site
+
+##### `RENDER_CONTENT(PAGE, SETTINGS)`
+
+Augments the content of the page before it is rendered as output.

docs/docs/page.md

@@ -1,3 +1,5 @@
+# Page Objects
+
 At Render Engine's core is the page. A page is a single unit of content. Pages are the building blocks of your site. If you want to display information on your site, you will need to create a page.
 
 ## BasePage
@@ -6,10 +8,63 @@ All `Page` objects inherit from `BasePage`, allowing for common functionality ac
 
 The `BasePage` is designed for Render Engine to render common `Page`-like objects. It is not designed to be used directly.
 
-::: src.render_engine.page.BasePage
+Bases: BaseObject
+
+This is the Base Page object.
+
+It was created to allow for the creation of custom page objects.
+
+This is not intended to be used directly.
+
+**Attributes:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `slug` |  |The slug of the page. Defaults to the `title` slugified. |
+| `content` |  |The content to be rendered by the page |
+| `parser` |  |The Parser used to parse the page's content. Defaults to `BasePageParser`. |
+| `reference` |  |The attribute to use as the reference for the page in the site's route list. Defaults to `slug`. |
+
+### Functions
+
+#### `url_for()`
+
+Returns the URL for the page including the first route.
+
+This gets the relative URL for a page.
+
+> [!NOTE]
+>
+> Pages don't have access to the Site attrs. You cannot get an abolute URL from a Page object.
+> Use `{{SITE_URL}}` in your templates to get the absolute URL.
+
+This is the preferred way to reference a page inside of a template.
 
 ## Page
 
 When you're creating a `Page`. You may want to provide a [`parser`](./parsers) or `content`/`content_path`. To do this, you will need to create a `Page` object.
 
-::: src.render_engine.page.Page
+Bases: [`BasePage`](./page?id=basepage)
+
+The general BasePage object used to make web pages.
+
+Pages can be rendered directly from a template or generated from a file.
+
+> [!NOTE]
+>
+> Not all attributes are defined by default (those that are marked optional) but will be checked for in other areas of the code.
+
+When you create a page, you specify variables passed into rendering template.
+
+**Attributes:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `content_path` | `str \| None` |The path to the file that will be used to generate the Page's `content`. |
+| `extension` | `str \| None` |The suffix to use for the page. Defaults to `.html`. |
+| `engine` | `str \| None` | If present, the engine to use for rendering the page. **This is normally not set and the `Site` 's engine will be used.** |
+| `reference` | `str \| None` |Used to determine how to reference the page in the `Site`'s route_list. Defaults to `slug`. |
+| `routes` | `str \| None` |The routes to use for the page. Defaults to `["./"]`. |
+| `template` | `str \| None` |The template used to render the page. If not provided, the `Site`'s `content`will be used. |
+| `Parser` | `type[BasePageParser]` |The parser to generate the page's `raw_content`. Defaults to `BasePageParser`. |
+| `title` | `str` |The title of the page. Defaults to the class name. |

docs/docs/parsers.md

@@ -2,7 +2,7 @@
 
 Parsers control how content is parsed and rendered.
 
-All [`Page`][src.render_engine.page.Page] and [`Collection`][src.render_engine.collection.Collection] objects have a `parser`
+All [`Page`](./page?id=page) and [`Collection`](./collection?id=collection) objects have a `parser`
 attribute that is used to parse the content of the object.
 
 Parsers use [staticmethods](https://docs.python.org/3/library/functions.html#staticmethod) to parse content. This allows you to create custom parsers that can be used to parse content in any way you want. Render Engine comes with a [BasePageParser](https://github.com/render-engine/render-engine-parser) and a [MarkdownPageParser](https://github.com/render-engine/render-engine-markdown) that can be used out of the box.