docs: init #67
Merged
docs: init #67
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Reviewer's GuideInitial scaffolding of Sphinx-based documentation: added configuration, build scripts, project metadata, and a complete set of placeholder .rst files for tutorials, how-tos, and API references. Class diagram for Sphinx documentation configurationclassDiagram
class conf_py {
+project: str
+copyright: str
+author: str
+release: str
+extensions: list
+templates_path: list
+source_suffix: str
+master_doc: str
+language: str
+exclude_patterns: list
+pygments_style: str
+pygments_dark_style: str
+html_theme: str
+html_theme_options: dict
+html_static_path: list
+html_css_files: list
+html_title: str
+html_short_title: str
+htmlhelp_basename: str
+latex_elements: dict
+latex_documents: list
+man_pages: list
+texinfo_documents: list
+epub_title: str
+epub_exclude_files: list
+intersphinx_mapping: dict
+todo_include_todos: bool
+autodoc_typehints: str
+autodoc_typehints_format: str
+autodoc_mock_imports: list
+copybutton_prompt_text: str
+copybutton_prompt_is_regexp: bool
+highlight_language: str
}
class Makefile {
+help
+clean
+serve
+open
+dev
+watch
+live
}
class live_sh {
+start sphinx-autobuild
+check conf.py
+change directory
}
Makefile --> conf_py
live_sh --> conf_py
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey there - I've reviewed your changes and they look great!
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location> `docs/conf.py:113` </location>
<code_context>
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"] if os.path.exists("_static") else []
+
+# Add external CSS files (Font Awesome for GitHub icon)
</code_context>
<issue_to_address>
**issue:** Conditional static path may cause missing assets if _static is absent.
This approach may result in missing static assets during documentation builds, particularly in CI or clean environments. To avoid inconsistent styling, always include '_static' in html_static_path and ensure the directory exists, or clearly document this requirement.
</issue_to_address>
### Comment 2
<location> `docs/live.sh:21` </location>
<code_context>
+sh live.sh
+
+# Or run sphinx-autobuild directly
+poetry run sphinx-autobuild . _build/html --port 8000 --host 0.0.0.0 --open-browser
+
+# Build with warnings treated as errors
</code_context>
<issue_to_address>
**suggestion:** The script assumes poetry is installed and available in PATH.
Add a check to verify that poetry is installed and in PATH, and display a clear error message if not.
</issue_to_address>
### Comment 3
<location> `docs/tutorial/02-installation.rst:22-23` </location>
<code_context>
+Using Poetry
+~~~~~~~~~~~~
+
+We recommend using ``Poetry`` to manage your dependencies. It it is used as default for this documentation.
+``pip`` can be used as equivalent.
+
</code_context>
<issue_to_address>
**issue (typo):** Typo: 'It it is used' should be 'It is used'.
Please update the sentence to 'It is used as default for this documentation.' or 'It is used by default in this documentation.'
```suggestion
We recommend using ``Poetry`` to manage your dependencies. It is used by default in this documentation.
``pip`` can be used as equivalent.
```
</issue_to_address>
### Comment 4
<location> `docs/tutorial/02-installation.rst:96-98` </location>
<code_context>
+ ]
+
+.. note::
+ When you autocreate clients and types from OpenAPI specification with tools like `heyapi.dev <https://heyapi.dev/>`_, this will also affect the naming of those components and types,eg.
+ ``RetrieveLanguages`` will become ``CmsRetrieveLanguages`` in the client sdk.
+
</code_context>
<issue_to_address>
**nitpick (typo):** Typo: 'eg.' should be 'e.g.'.
Use the correct abbreviation for clarity.
```suggestion
.. note::
When you autocreate clients and types from OpenAPI specification with tools like `heyapi.dev <https://heyapi.dev/>`_, this will also affect the naming of those components and types, e.g.
``RetrieveLanguages`` will become ``CmsRetrieveLanguages`` in the client sdk.
```
</issue_to_address>
### Comment 5
<location> `docs/tutorial/02-installation.rst:148` </location>
<code_context>
+Languages Support
+-----------------
+
+- djnagocms-rest supports languages out of the box.
+- Djnago CMS needs to be configured to use languages.
+- A single language must always be set in order to use the API.
</code_context>
<issue_to_address>
**issue (typo):** Typo: 'djnagocms-rest' should be 'djangocms-rest'.
```suggestion
- djangocms-rest supports languages out of the box.
```
</issue_to_address>
### Comment 6
<location> `docs/tutorial/02-installation.rst:238-239` </location>
<code_context>
+If you want to serve multiple sites from a single instance, you can use the ``SiteContextMiddleware`` to set the site context on the request.
+This requires ``Django Sites`` framework to be installed and configured.
+
+Your can pass the site ID in the request headers with the ``X-Site-ID`` property set to the site ID.
+The Middleware will then set the site context on the request.
+
</code_context>
<issue_to_address>
**issue (typo):** Typo: 'Your can pass' should be 'You can pass'.
```suggestion
You can pass the site ID in the request headers with the ``X-Site-ID`` property set to the site ID.
The Middleware will then set the site context on the request.
```
</issue_to_address>
### Comment 7
<location> `docs/tutorial/02-installation.rst:265` </location>
<code_context>
+ ...
+ ]
+
+ # default site id, you likely wnat to change this using env variable in production
+ SITE_ID = 1
+
</code_context>
<issue_to_address>
**issue (typo):** Typo: 'wnat' should be 'want'.
```suggestion
# default site id, you likely want to change this using env variable in production
```
</issue_to_address>
### Comment 8
<location> `docs/tutorial/02-installation.rst:270` </location>
<code_context>
+
+.. code-block:: python
+
+ CORS_ALLOW_ALL_ORIGINS=True # development seting, disable in production
+ CORS_ALLOWED_ORIGINS = [
+ "https://frontend.com", # your production frontend domain
</code_context>
<issue_to_address>
**issue (typo):** Typo: 'seting' should be 'setting'.
```suggestion
CORS_ALLOW_ALL_ORIGINS=True # development setting, disable in production
```
</issue_to_address>
### Comment 9
<location> `docs/reference/plugins.rst:18` </location>
<code_context>
+
+Howto
+------
+- :doc:`Plugin Creation & Serialization <../how-to/011-plugin-creation>`
+
+CMS Reference
</code_context>
<issue_to_address>
**issue (bug_risk):** Incorrect link: '011-plugin-creation' should be '02-plugin-creation'.
</issue_to_address>
### Comment 10
<location> `docs/how-to/index.rst:31` </location>
<code_context>
+Contribute
+----------
+
+We are always looking for contributions to improve the documentation. If you are working on an implementation scenario. Plese share your experience and create a small implementation guide for others to follow.
+
+- **GitHub Repository**: `djangocms-rest <https://github.com/django-cms/djangocms-rest>`_
</code_context>
<issue_to_address>
**issue (typo):** Typo: 'Plese' should be 'Please'.
```suggestion
We are always looking for contributions to improve the documentation. If you are working on an implementation scenario. Please share your experience and create a small implementation guide for others to follow.
```
</issue_to_address>
### Comment 11
<location> `docs/how-to/01-use-multi-site.rst:6-7` </location>
<code_context>
+
+In this short guide, we will show you how to use the multi-site functionality in your frontend app.
+
+We will use ``vue.js`` to fetch data from a single django CMS instance with multiple sites. This implemenation
+guide can easily be adapted to other frontend frameworks.
+
</code_context>
<issue_to_address>
**issue (typo):** Typo: 'implemenation' should be 'implementation'.
```suggestion
We will use ``vue.js`` to fetch data from a single django CMS instance with multiple sites. This implementation
guide can easily be adapted to other frontend frameworks.
```
</issue_to_address>
### Comment 12
<location> `docs/conf.py:1` </location>
<code_context>
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
</code_context>
<issue_to_address>
**issue (complexity):** Consider simplifying the configuration by removing commented defaults, listing only used extensions, and moving theme CSS variables to a static file.
Here’s how you can trim down noise without losing any behavior:
1. Remove all commented‐out defaults (Sphinx uses them anyway).
2. Only list extensions you actually use.
3. Pull your theme CSS variables into a static file.
```python
# conf.py
import os, sys
sys.path.insert(0, os.path.abspath(".."))
project = "djangocms-rest"
copyright = "2024, Django CMS Association and contributors"
author = "Django CMS Association and contributors"
release = "0.1.0"
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.intersphinx",
"sphinx.ext.todo",
"sphinx_autodoc_typehints",
"sphinx_copybutton",
"sphinx_tabs.tabs",
]
templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
html_theme = "furo"
html_theme_options = {
"source_repository": "https://github.com/django-cms/djangocms-rest",
"source_branch": "main",
"source_directory": "/docs/",
"footer_icons": [
{
"name": "GitHub",
"url": "https://github.com/django-cms/djangocms-rest",
"class":"fa-brands fa-solid fa-github fa-2x",
},
],
}
html_static_path = ["_static"]
html_css_files = [
"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css",
"theme_overrides.css",
]
intersphinx_mapping = {
"python": ("https://docs.python.org/3/", None),
"django": ("https://docs.djangoproject.com/en/stable/", None),
}
todo_include_todos = True
autodoc_typehints = "description"
autodoc_typehints_format = "short"
autodoc_mock_imports = ["django", "djangorestframework", "cms", "djangocms_link", "djangocms_text"]
copybutton_prompt_text = r">>> |\.\.\. |\$ "
copybutton_prompt_is_regexp = True
highlight_language = "python3"
```
And in `_static/theme_overrides.css`:
```css
/* light */
:root {
--color-code-background: #f8f9fa;
--color-code-foreground: #333;
--font-stack: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
--font-stack--monospace: 'SF Mono', 'Monaco', 'Roboto Mono', monospace;
}
/* dark */
@media (prefers-color-scheme: dark) {
:root {
--color-code-background: #2d3748;
--color-code-foreground: #e2e8f0;
}
}
```
</issue_to_address>
### Comment 13
<location> `docs/conf.py:21` </location>
<code_context>
import os
import sys
sys.path.insert(0, os.path.abspath(".."))
# -- Project information -----------------------------------------------------
project = "djangocms-rest"
copyright = "2024, Django CMS Association and contributors"
author = "Django CMS Association and contributors"
# The full version, including alpha/beta/rc tags
release = "0.1.0"
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.doctest",
"sphinx.ext.intersphinx",
"sphinx.ext.todo",
"sphinx.ext.coverage",
"sphinx.ext.mathjax",
"sphinx.ext.ifconfig",
"sphinx.ext.viewcode",
"sphinx.ext.napoleon",
"sphinx_autodoc_typehints",
"sphinx_copybutton",
"sphinx_tabs.tabs",
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = ".rst"
# The master toctree document.
master_doc = "index"
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = "en"
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = "default"
pygments_dark_style = "dracula"
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = "furo"
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
html_theme_options = {
"source_repository": "https://github.com/django-cms/djangocms-rest",
"source_branch": "main",
"source_directory": "/docs/",
"footer_icons": [
{
"name": "GitHub",
"url": "https://github.com/django-cms/djangocms-rest",
"html": "",
"class": "fa-brands fa-solid fa-github fa-2x",
},
],
"light_css_variables": {
"color-code-background": "#f8f9fa",
"color-code-foreground": "#333",
"font-stack": "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', sans-serif",
"font-stack--monospace": "'SF Mono', 'Monaco', 'Inconsolata', 'Roboto Mono', 'Source Code Pro', 'Droid Sans Mono', 'Consolas', 'Monaco', 'Lucida Console', 'Liberation Mono', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Courier New', monospace",
},
"dark_css_variables": {
"color-code-background": "#2d3748",
"color-code-foreground": "#e2e8f0",
},
}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["_static"] if os.path.exists("_static") else []
# Add external CSS files (Font Awesome for GitHub icon)
html_css_files = [
"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/fontawesome.min.css",
"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/solid.min.css",
"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/brands.min.css",
]
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
html_title = "djangocms-rest"
# A shorter title for the navigation bar. Default is the same as html_title.
html_short_title = "djangocms-rest"
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
# html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
# html_favicon = '_static/favicon.ico'
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = "djangocmsrestdoc"
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(
master_doc,
"djangocmsrest.tex",
"djangocms-rest Documentation",
"Django CMS Association and contributors",
"manual",
),
]
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [(master_doc, "djangocmsrest", "djangocms-rest Documentation", [author], 1)]
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(
master_doc,
"djangocmsrest",
"djangocms-rest Documentation",
author,
"djangocmsrest",
"API endpoints for django CMS",
"Miscellaneous",
),
]
# -- Options for Epub output -------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#
# epub_identifier = ''
# A unique identification for the text.
#
# epub_uid = ''
# A list of files that should not be packed into the epub file.
epub_exclude_files = ["search.html"]
# -- Extension configuration -------------------------------------------------
# -- Options for intersphinx extension ---------------------------------------
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {
"python": ("https://docs.python.org/3/", None),
"django": ("https://docs.djangoproject.com/en/stable/", None),
}
# -- Options for todo extension ----------------------------------------------
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
# -- Options for autodoc extension -------------------------------------------
# Automatically extract typehints when specified and place them in
# descriptions of the relevant function/method.
autodoc_typehints = "description"
# Don't show typehints in the signature
autodoc_typehints_format = "short"
# Mock imports for autodoc
autodoc_mock_imports = [
"django",
"djangorestframework",
"cms",
"djangocms_link",
"djangocms_text",
]
# -- Options for copybutton extension ----------------------------------------
copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
copybutton_prompt_is_regexp = True
# -- Options for better code highlighting ------------------------------------
# Ensure code blocks are properly highlighted
highlight_language = "python3"
</code_context>
<issue_to_address>
**issue (code-quality):** Don't assign to builtin variable `copyright` ([`avoid-builtin-shadow`](https://docs.sourcery.ai/Reference/Default-Rules/comments/avoid-builtin-shadow/))
<br/><details><summary>Explanation</summary>Python has a number of `builtin` variables: functions and constants that
form a part of the language, such as `list`, `getattr`, and `type`
(See https://docs.python.org/3/library/functions.html).
It is valid, in the language, to re-bind such variables:
```python
list = [1, 2, 3]
```
However, this is considered poor practice.
- It will confuse other developers.
- It will confuse syntax highlighters and linters.
- It means you can no longer use that builtin for its original purpose.
How can you solve this?
Rename the variable something more specific, such as `integers`.
In a pinch, `my_list` and similar names are colloquially-recognized
placeholders.</details>
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
| fi | ||
|
|
||
| # Start sphinx-autobuild | ||
| poetry run sphinx-autobuild . _build/html --port 8000 --host 0.0.0.0 --open-browser No newline at end of file |
There was a problem hiding this comment.
suggestion: The script assumes poetry is installed and available in PATH.
Add a check to verify that poetry is installed and in PATH, and display a clear error message if not.
| @@ -0,0 +1,264 @@ | |||
| # Configuration file for the Sphinx documentation builder. | |||
There was a problem hiding this comment.
issue (complexity): Consider simplifying the configuration by removing commented defaults, listing only used extensions, and moving theme CSS variables to a static file.
Here’s how you can trim down noise without losing any behavior:
- Remove all commented‐out defaults (Sphinx uses them anyway).
- Only list extensions you actually use.
- Pull your theme CSS variables into a static file.
# conf.py
import os, sys
sys.path.insert(0, os.path.abspath(".."))
project = "djangocms-rest"
copyright = "2024, Django CMS Association and contributors"
author = "Django CMS Association and contributors"
release = "0.1.0"
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.intersphinx",
"sphinx.ext.todo",
"sphinx_autodoc_typehints",
"sphinx_copybutton",
"sphinx_tabs.tabs",
]
templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
html_theme = "furo"
html_theme_options = {
"source_repository": "https://github.com/django-cms/djangocms-rest",
"source_branch": "main",
"source_directory": "/docs/",
"footer_icons": [
{
"name": "GitHub",
"url": "https://github.com/django-cms/djangocms-rest",
"class":"fa-brands fa-solid fa-github fa-2x",
},
],
}
html_static_path = ["_static"]
html_css_files = [
"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css",
"theme_overrides.css",
]
intersphinx_mapping = {
"python": ("https://docs.python.org/3/", None),
"django": ("https://docs.djangoproject.com/en/stable/", None),
}
todo_include_todos = True
autodoc_typehints = "description"
autodoc_typehints_format = "short"
autodoc_mock_imports = ["django", "djangorestframework", "cms", "djangocms_link", "djangocms_text"]
copybutton_prompt_text = r">>> |\.\.\. |\$ "
copybutton_prompt_is_regexp = True
highlight_language = "python3"And in _static/theme_overrides.css:
/* light */
:root {
--color-code-background: #f8f9fa;
--color-code-foreground: #333;
--font-stack: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
--font-stack--monospace: 'SF Mono', 'Monaco', 'Roboto Mono', monospace;
}
/* dark */
@media (prefers-color-scheme: dark) {
:root {
--color-code-background: #2d3748;
--color-code-foreground: #e2e8f0;
}
}| # -- Project information ----------------------------------------------------- | ||
|
|
||
| project = "djangocms-rest" | ||
| copyright = "2024, Django CMS Association and contributors" |
There was a problem hiding this comment.
issue (code-quality): Don't assign to builtin variable copyright (avoid-builtin-shadow)
Explanation
Python has a number ofbuiltin variables: functions and constants thatform a part of the language, such as
list, getattr, and type(See https://docs.python.org/3/library/functions.html).
It is valid, in the language, to re-bind such variables:
list = [1, 2, 3]However, this is considered poor practice.
- It will confuse other developers.
- It will confuse syntax highlighters and linters.
- It means you can no longer use that builtin for its original purpose.
How can you solve this?
Rename the variable something more specific, such as integers.
In a pinch, my_list and similar names are colloquially-recognized
placeholders.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #67 +/- ##
=======================================
Coverage 90.83% 90.83%
=======================================
Files 18 18
Lines 851 851
Branches 98 98
=======================================
Hits 773 773
Misses 48 48
Partials 30 30 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>
Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>
Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>
Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>
Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>
Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>
…o authentication, custom user requirements, and security enhancements
…ation documentation
fsbraun
approved these changes
Oct 26, 2025
There was a problem hiding this comment.
@metaforx That's a great start! Instead of getting lost in a nitty-gritty line-editing excercise, I'd suggest we take it from here iteratively (PR by PR).
Some thoughts I have are:
- Normalize the installation docs to using pip instead of poetry (as we do throughout hte django-cms organization)
- Maybe deepen the tutorial
- Add readthedocs support
Let me make the next iteration!
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Initial Sphinx Documentation
It is meant as a first draft to define structure and detail level.
An external review is necessary because someone who is not involved in the writing process can often catch many mistakes just by reading it.
Documentation includes:
API Reference:
The API reference should not be too detailed because we should focus on OpenAPI as the source of truth. Nevertheless, it might be helpful to check what responses to expect and which Django CMS documentation can be referenced for further instructions. For example, this could be useful for menu building.
The endpoints have been described in detail but have not yet been worked through for menus, submenus, and breadcrumbs.
Summary by Sourcery
Initialize Sphinx documentation for djangocms-rest by adding configuration, build scripts, project metadata, and a skeleton of guide and reference content
Build:
Documentation: