Skip to content

Commit 4b0ea14

Browse files
metaforxsourcery-ai[bot]fsbraun
authored
docs: init (#67)
* docs: init djangocms-rest documentation * docs: Update static file handling in Sphinx configuration * Update docs/tutorial/02-installation.rst Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com> * Update docs/tutorial/02-installation.rst Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com> * Update docs/how-to/01-use-multi-site.rst Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com> * Update docs/how-to/index.rst Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com> * Update docs/tutorial/02-installation.rst Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com> * Update docs/tutorial/02-installation.rst Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com> * Update reference to Plugin Creation & Serialization in plugins.rst * Update repository references in README and installation documentation * Update installation documentation with additional references to Django authentication, custom user requirements, and security enhancements * fixes openapi benefits listing * Clarify note on retrieving page and placeholder objects in plugin creation documentation * Add basic auto-serialization example * Add hint for generating frontend URLs in plugin creation documentation * Update link_text in plugin creation documentation for clarity --------- Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com> Co-authored-by: Fabian Braun <[email protected]>
1 parent 505f469 commit 4b0ea14

27 files changed

+4178
-1
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -411,4 +411,4 @@ like to change.
411411

412412
## License
413413

414-
[BSD-3](https://github.com/fsbraun/djangocms-rest/blob/main/LICENSE)
414+
[BSD-3](https://github.com/django-cms/djangocms-rest/blob/main/LICENSE)

‎docs/.gitignore‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Sphinx build directory
2+
_build/
3+
4+
# Python cache
5+
__pycache__/
6+
*.pyc
7+
*.pyo
8+
9+
# IDE files
10+
.vscode/
11+
.idea/
12+
13+
# OS files
14+
.DS_Store
15+
Thumbs.db

‎docs/Makefile‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile clean serve open dev watch live
16+
17+
# Custom targets for convenience
18+
clean:
19+
rm -rf $(BUILDDIR)/*
20+
21+
serve:
22+
@echo "Starting documentation server at http://localhost:8000"
23+
@python -m http.server 8000 --directory $(BUILDDIR)/html
24+
25+
open:
26+
@echo "Opening documentation in browser..."
27+
@open $(BUILDDIR)/html/index.html
28+
29+
# Development targets
30+
dev:
31+
@echo "Building documentation in development mode..."
32+
@$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) -W --keep-going
33+
34+
watch:
35+
@echo "Watching for changes and rebuilding..."
36+
@while true; do \
37+
inotifywait -r -e modify,create,delete .; \
38+
$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS); \
39+
done
40+
41+
live:
42+
@echo "Starting live documentation server with auto-reload..."
43+
@echo "Server will be available at http://localhost:8000"
44+
@echo "Press Ctrl+C to stop"
45+
@sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" --port 8000 --host 0.0.0.0 --open-browser
46+
47+
# Catch-all target: route all unknown targets to Sphinx using the new
48+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
49+
%: Makefile
50+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/README.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# djangocms-rest Documentation
2+
3+
This directory contains the documentation for djangocms-rest, built with Sphinx.
4+
5+
## Setup
6+
7+
### Using Poetry (Recommended)
8+
9+
```bash
10+
# From project root, install all dependencies including docs
11+
poetry install --with dev
12+
13+
# Navigate to the docs directory
14+
cd docs
15+
16+
# Build the documentation
17+
make html
18+
```
19+
20+
### Alternative: Using pip
21+
22+
```bash
23+
# From project root, install development dependencies
24+
pip install -e ".[dev]"
25+
26+
# Navigate to the docs directory
27+
cd docs
28+
29+
# Build the documentation
30+
make html
31+
```
32+
33+
## Building Documentation
34+
35+
### Build HTML Documentation
36+
37+
```bash
38+
# Build the documentation
39+
make html
40+
41+
# Or use sphinx-build directly
42+
sphinx-build -b html . _build/html
43+
```
44+
45+
### View Documentation Locally
46+
47+
```bash
48+
# Build and serve documentation
49+
make serve
50+
51+
# Or build and open in browser
52+
make html
53+
make open
54+
```
55+
56+
### Development Mode with Live Reload
57+
58+
```bash
59+
# Start live documentation server with auto-reload (recommended)
60+
sh live.sh
61+
62+
# Or run sphinx-autobuild directly
63+
poetry run sphinx-autobuild . _build/html --port 8000 --host 0.0.0.0 --open-browser
64+
65+
# Build with warnings treated as errors
66+
make dev
67+
68+
# Watch for changes and rebuild automatically
69+
make watch
70+
```
71+
72+
## Available Make Targets
73+
74+
- `make html` - Build HTML documentation
75+
- `make clean` - Clean build directory
76+
- `make serve` - Serve documentation on http://localhost:8000
77+
- `make open` - Open documentation in browser
78+
- `make live` - Start live server with auto-reload (recommended for development)
79+
- `make dev` - Build in development mode with warnings
80+
- `make watch` - Watch for changes and rebuild automatically
81+
- `make help` - Show all available targets
82+
83+
## Documentation Structure
84+
85+
The documentation is organized into logical sections:
86+
87+
### Tutorial
88+
- `tutorial/01-quickstart.rst` - Quick start guide
89+
- `tutorial/02-installation.rst` - Installation guide
90+
- `tutorial/03-openapi-documentation.rst` - OpenAPI documentation guide
91+
92+
### How-to Guides
93+
- `how-to/01-use-multi-site.rst` - Multi-site configuration guide
94+
- `how-to/02-plugin-creation.rst` - Plugin creation guide
95+
96+
### Reference
97+
- `reference/index.rst` - API overview
98+
- `reference/pages.rst` - Pages API reference
99+
- `reference/languages.rst` - Languages API reference
100+
- `reference/placeholders.rst` - Placeholders API reference
101+
- `reference/plugins.rst` - Plugins API reference
102+
- `reference/menu.rst` - Menu API reference
103+
- `reference/breadcrumbs.rst` - Breadcrumbs API reference
104+
- `reference/submenu.rst` - Submenu API reference
105+
106+
### Additional
107+
- `contributing.rst` - Contributing guide
108+
- `changelog.rst` - Version history
109+
110+
## Configuration
111+
112+
The documentation is configured in `conf.py`. Key settings include:
113+
114+
- **Theme**: Furo theme (modern, clean design with sidebar navigation)
115+
- **Extensions**: autodoc, intersphinx, napoleon, sphinx-tabs, sphinx-copybutton, etc.
116+
- **Intersphinx**: Links to Python, Django, DRF, and django CMS documentation
117+
- **Mock imports**: Django and django CMS modules are mocked for autodoc
118+
- **GitHub Integration**: Source repository links and GitHub icon in footer
119+
120+
## Contributing to Documentation
121+
122+
1. Make changes to the `.rst` files
123+
2. Build the documentation to check for errors: `make html`
124+
3. Test locally: `make serve`
125+
4. Submit a pull request
126+
127+
## Troubleshooting
128+
129+
### Common Issues
130+
131+
**ImportError: No module named 'django'**
132+
- This is expected when building documentation without Django installed
133+
- The `conf.py` file includes mock imports for Django modules
134+
135+
**Sphinx build errors**
136+
- Check that all dependencies are installed: `poetry install --with dev` or `pip install -e ".[dev]"`
137+
- Ensure you're in the `docs` directory when running commands
138+
- Check the build output for specific error messages
139+
140+
**Missing intersphinx links**
141+
- The documentation links to external documentation (Python, Django, etc.)
142+
- These links may not work offline
143+
- This is normal behavior
144+
145+
### Getting Help
146+
147+
- Check the [Sphinx documentation](https://www.sphinx-doc.org/)
148+
- Review the [Read the Docs theme documentation](https://sphinx-rtd-theme.readthedocs.io/)
149+
- Open an issue on the project repository

‎docs/_static/.gitkeep‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# This file ensures the _static directory is tracked by git
2+
# Sphinx will populate this directory with static assets during build

‎docs/changelog.rst‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
=========
2+
Changelog
3+
=========
4+
5+
.. changelog::
6+
:towncrier: ../
7+
8+
0.8.1 (2025-08-29)
9+
==================
10+
11+
Bugfixes
12+
--------
13+
14+
* fix: Package data not included in wheel (#48)
15+
16+
0.8.0 (2025-08-28)
17+
==================
18+
19+
Features
20+
--------
21+
22+
* feat: Add comprehensive documentation for django CMS REST
23+
* feat: Add menu endpoints (#49)
24+
* feat: Add RESTRenderer (#42)
25+
* feat: frontend URL handling with absolute URL generation. (#36)
26+
* feat: extend page serializer with additional page fields (#35)
27+
* feat: add public language support (#27)
28+
* feat: update code to support Django CMS 5 (#29)
29+
* feat: Refactoring for improved Open API & typing support (allows: automatic schema generation) (#20)
30+
31+
Bugfixes
32+
--------
33+
34+
* fix: Enable caching for placeholder serialization and rendering. (#31)
35+
* fix: open api schema validation (#34)
36+
* fix: Update test requirements (#25)
37+
* fix: Update github actions and readme (#12)
38+
39+
Documentation
40+
-------------
41+
42+
* docs: Update documentation references from "django CMS REST" to "djangocms-rest"
43+
* docs: Update readme (#39)
44+
* docs: update docs (#26)
45+
* docs: initial project outline
46+
47+
0.1.0 (2024-05-24)
48+
==================
49+
50+
Features
51+
--------
52+
53+
* Initial commit with basic functionality for placeholders
54+
* Restructure api
55+
* Optionally include HTML in placeholder responses
56+
* Respect page viewing permissions
57+
* Add first test
58+
* Code refactoring
59+
* Fix: page detail by path
60+
* View naming convention cms-model-list/detail
61+
* Update language list url name
62+
* Update rendering test
63+
64+
Bugfixes
65+
--------
66+
67+
* Fix: Language endpoint offers pages list
68+
* Fix test actions
69+
* Fix ruff issues
70+
* Update action to upload codecov
71+
* Update .coveragerc
72+
73+
Documentation
74+
-------------
75+
76+
* Docs
77+
* Update readme
78+
* Update README.md
79+
80+
Development
81+
-----------
82+
83+
* Bump codecov/codecov-action from 4.0.1 to 4.4.1
84+
* Bump codecov/codecov-action from 4.4.1 to 4.5.0
85+
* Bump codecov/codecov-action from 4.5.0 to 4.6.0
86+
* Bump codecov/codecov-action from 4.6.0 to 5.0.2
87+
* Bump codecov/codecov-action from 5.0.2 to 5.3.1
88+
* Bump codecov/codecov-action from 5.3.1 to 5.4.0
89+
* Bump codecov/codecov-action from 5.4.0 to 5.4.2
90+
* Bump codecov/codecov-action from 5.4.2 to 5.4.3
91+
* Bump codecov/codecov-action from 5.4.3 to 5.5.0
92+
* Bump codecov/codecov-action from 5.5.0 to 5.5.1
93+
* change supported version of `django-cms` (#22)
94+
* fix: remove Node.js setup and frontend build from workflow (#28)
95+
* chore: Add django CMS 4.1 support, simplify preview views/ruff format (#40)
96+
* chore(deps): bump actions/checkout from 4 to 5 (#43)
97+
* chore(deps): bump actions/setup-python from 5 to 6 (#52)
98+
* chore(deps): bump codecov/codecov-action from 5.5.0 to 5.5.1 (#51)
99+
* chore: Update documentation configuration and checks
100+
* chore: Bump version from 0.1.0a to 0.8.0 (#46)
101+
* chore: Update readme (#47)
102+
* fix: pyproject.toml
103+
* update pyproj.toml
104+
* Upodate version number
105+
* Update test.yml
106+
107+
Recent Development (2025-10-18)
108+
==============================
109+
110+
Documentation
111+
-------------
112+
113+
* docs: revise contributing guidelines to emphasize community involvement and streamline setup instructions
114+
* docs: refine multi-site guide and installation documentation, enhance language endpoint descriptions, and add planned guides section
115+
* docs: enhance multi-site and quickstart guides with CORS clarification and updated API testing instructions
116+
* docs: update endpoint headings for consistency and enhance multi-site installation instructions
117+
* docs: standardize API section headings and update endpoint descriptions for clarity
118+
* docs: update API documentation to reflect port change to 8080 for local testing
119+
* docs: update documentation structure and content, including new quick start guide and plugin creation instructions
120+
* docs: update multi-site guide with detailed setup instructions and Vue.js example
121+
* docs: enhance multi-site usage guide with Vue.js example and additional resources
122+
* docs: update API endpoint URLs in documentation to use port 8080
123+
* docs: imrove api references
124+
* docs: fix typo in installation instructions
125+
* docs: simplify installation instructions
126+
* docs: improved installation instructions, and minor doc fixes
127+
* docs: Enhance index documentation with motivation and key features
128+
* docs: Update and expand API documentation for various endpoints
129+
* docs: Add `preview` query parameter to API documentation for pages and languages
130+
* docs: Refactor API documentation for languages and pages endpoints
131+
132+
Features
133+
--------
134+
135+
* feat: add OpenAPI support for "preview" query parameter (#53)
136+
* feat: add OpenAPI schema decorator for `MenuView` and include `namespace` in `NavigationNodeSerializer`
137+
* feat: add site middleware (#50)
138+
139+
Bugfixes
140+
--------
141+
142+
* fix: update `child` field in `NavigationNodeListSerializer` to accept multiple instances
143+
* fix: wrap menu serializer data with return_key in `MenuView` response
144+
* fix: exclude method_schema_decorator from test coverage
145+
* fix: mark method_schema_decorator and related lines as uncovered

0 commit comments

Comments
 (0)