From 044196244c355d4e0e125b6c4a8bd1f637b24dbc Mon Sep 17 00:00:00 2001 From: Stuart Maxwell Date: Fri, 15 Nov 2024 17:48:26 +1300 Subject: [PATCH] Update docs --- README.md | 37 ++++++++++++++++++++++++++++++++-- docs/configuration.md | 29 +++++++++++++++++++++++++++ docs/index.md | 4 ++++ docs/installation.md | 46 +++++++++++++++++++++++++++++++++++++++++++ justfile | 8 ++------ uv.lock | 2 +- 6 files changed, 117 insertions(+), 9 deletions(-) create mode 100644 docs/configuration.md create mode 100644 docs/installation.md diff --git a/README.md b/README.md index 0d09fa6..790564b 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,11 @@ This package uses semantic versioning, but until we reach version 1.x.x, the fol - MINOR version indicates that an incompatible or breaking change has been introduced. - PATCH version indicates a bug fix or a backward compatible change. -If you choose to use this package prior to version 1.x being release, please pin your requirements to a specific minor version, e.g. `djpress==0.3.*` +If you choose to use this package prior to version 1.x being release, please pin your requirements to a specific minor version, e.g. `djpress~=0.11.0` ## Installation -- Install `djpress` by adding it to your requirements file, e.g. `djpress==0.3.*` (see versioning note, above). +- Install `djpress` by adding it to your requirements file, e.g. `djpress~=0.11.0` (see versioning note, above). - Add it to your `INSTALLED_APPS` in Django: ```python @@ -29,6 +29,8 @@ INSTALLED_APPS = [ - Add the URLs to your project's main `urls.py` file. +The following will set DJ Press to be available at the root of your site, e.g. `https://example.com/` + ```python from django.urls import path, include @@ -39,10 +41,41 @@ urlpatterns = [ ] ``` +If you want your blog to be in a subdirectory, use something like the following: + +```python +from django.urls import path, include + +urlpatterns = [ + # ... + path("blog/", include("djpress.urls")), + # ... +] +``` + - Run migrations: `python3 manage.py migrate` > Note that this relies on the Django Admin for content management, so ensure that you have a user with at least `staff` status to manage content. +## Configuration + +In your settings.py file, create a `DJPRESS_SETTINGS` dictionary. Here are some common settings: + +```python +# DJPress settings +DJPRESS_SETTINGS = { + "BLOG_TITLE": "My Awesome Blog", + "POST_PREFIX": "{{ year }}/{{ month }}", +} +``` + +There are lots more settings available. Please checks the docs or look at the source code: +[src/djpress/app_settings.py](https://github.com/stuartmaxwell/djpress/blob/main/src/djpress/app_settings.py) + +## Documentation + +Documentation is a work-in-progress but is available on GitHub Pages: + ## Badges [![codecov](https://codecov.io/github/stuartmaxwell/djpress/graph/badge.svg?token=IOS7BCD54B)](https://codecov.io/github/stuartmaxwell/djpress) diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..572cf4a --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,29 @@ +# Configuration + +## DJ Press Settings + +In your settings.py file, create a `DJPRESS_SETTINGS` dictionary. Here are some common settings: + +```python +# DJPress settings +DJPRESS_SETTINGS = { + "BLOG_TITLE": "My Awesome Blog", + "POST_PREFIX": "{{ year }}/{{ month }}", +} +``` + +There are lots more settings available. Please checks the docs or look at the source code: +[src/djpress/app_settings.py](https://github.com/stuartmaxwell/djpress/blob/main/src/djpress/app_settings.py) + +## Themes + +There are two themes included with DJ Press: "default" and "simple". They can be configured as follows: + +```python +# DJPress settings +DJPRESS_SETTINGS = { + "THEME": "simple", +} +``` + +To create, your own theme please read the [Theme documentation](themes.md) diff --git a/docs/index.md b/docs/index.md index c3e4652..d130792 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,6 +3,8 @@ Welcome to the documentation site for DJ Press. This is a work in progress, but the following key areas are mostly complete: +- [Installation](installation.md) +- [Configuration](configuration.md) - [URL Structure](url_structure.md) - [Template Tags](templatetags.md) - [Themes](themes.md) @@ -13,6 +15,8 @@ complete: --- maxdepth: 2 --- +installation +configuration url_structure templatetags themes diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..2749788 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,46 @@ +# Installation + +> Note: If you choose to use this package prior to version 1.x being release, please pin your requirements to a specific minor version, e.g. `djpress~=0.11.0` + +- Install `djpress` by adding it to your requirements file, e.g. `djpress~=0.11.0` (see versioning note, above). +- Add it to your `INSTALLED_APPS` in Django: + +```python +INSTALLED_APPS = [ + # ... + "djpress.apps.DjpressConfig", + # ... +] +``` + +- Add the URLs to your project's main `urls.py` file. + +The following will set DJ Press to be available at the root of your site, e.g. `https://example.com/` + +```python +from django.urls import path, include + +urlpatterns = [ + # ... + path("", include("djpress.urls")), + # ... +] +``` + +If you want your blog to be in a subdirectory, e.g. `https://example.com/blog/`, use something like the following: + +```python +from django.urls import path, include + +urlpatterns = [ + # ... + path("blog/", include("djpress.urls")), + # ... +] +``` + +- Run migrations: `python3 manage.py migrate` + +> Note that DJ Press relies on the Django Admin for content management, so ensure that you have a user with at least `staff` status to manage content. + +- Access your site's admin panel to manage content, e.g. `https://example.com/admin/djpress/` diff --git a/justfile b/justfile index d004337..bc2f00c 100644 --- a/justfile +++ b/justfile @@ -104,10 +104,6 @@ pc-up: pc-run: {{uv-tool}} pre-commit run --all-files -# Sphinx -sphinx: - @{{SPHINXBUILD}} -M "{{SOURCEDIR}}" "{{BUILDDIR}}" {{SPHINXOPTS}} - -# Live HTML build with auto-reload -sphinx-live: +# Use Sphinx to build and view the documentation +docs: uv run sphinx-autobuild -b html "{{SOURCEDIR}}" "{{BUILDDIR}}" {{SPHINXOPTS}} diff --git a/uv.lock b/uv.lock index b2cfec3..cbc4b51 100644 --- a/uv.lock +++ b/uv.lock @@ -289,7 +289,7 @@ wheels = [ [[package]] name = "djpress" -version = "0.11.0" +version = "0.11.2" source = { editable = "." } dependencies = [ { name = "django" },