Skip to content

Commit e1e4cfc

Browse files
jacklinkejacklinke
committed
Improving docs
1 parent cb309a8 commit e1e4cfc

7 files changed

Lines changed: 443 additions & 39 deletions

File tree

‎README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ django-help is a powerful and flexible Django package that provides a multilingu
7171
- django-taggit 6.1+: For tagging functionality
7272
- python-frontmatter 1.1+: For parsing Markdown files with metadata
7373
- django-crispy-forms 2.3+: For enhanced form rendering
74+
- crispy-bootstrap5 2024.2+: For Bootstrap 5 styling in crispy forms
7475

7576
## Installation
7677

@@ -91,6 +92,7 @@ INSTALLED_APPS = [
9192
'markdownx',
9293
'taggit',
9394
'crispy_forms',
95+
'crispy_bootstrap5',
9496
]
9597
```
9698

@@ -194,6 +196,24 @@ activate('es') # Switch to Spanish
194196
# Your view logic here
195197
```
196198

199+
### Display help content in your templates:
200+
201+
```html
202+
{% load django_help_tags %}
203+
204+
<!-- Display help button for the current path -->
205+
{% django_help_current_path %}
206+
207+
<!-- Display help button for a specific category -->
208+
{% django_help_category "getting-started" %}
209+
210+
<!-- Display help button for a specific article slug -->
211+
{% django_help_slug "how-to-reset-password" %}
212+
213+
<!-- Display help button for a specific tag -->
214+
{% django_help_tag "account-management" %}
215+
```
216+
197217
## Import/Export Functionality
198218

199219
django-help provides powerful import and export capabilities for managing your help content.

‎docs/conf.py‎

Lines changed: 84 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,94 @@
1-
"""Sphinx configuration."""
1+
"""Sphinx configuration for django-help documentation."""
22

3+
import sys
4+
from datetime import datetime
5+
from pathlib import Path
6+
7+
8+
# Add the project root directory to the Python path
9+
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
10+
11+
# Project information
312
project = "django-help"
413
author = "Jack Linke"
5-
copyright = "2024, Jack Linke"
14+
copyright = f"{datetime.now().year}, {author}"
15+
16+
# General configuration
617
extensions = [
718
"sphinx.ext.autodoc",
819
"sphinx.ext.napoleon",
20+
"sphinx.ext.intersphinx",
21+
"sphinx.ext.viewcode",
922
"sphinx_click",
1023
"myst_parser",
1124
]
12-
autodoc_typehints = "description"
25+
26+
# Any paths that contain templates here, relative to this directory.
27+
templates_path = ["_templates"]
28+
29+
# List of patterns, relative to source directory, that match files and
30+
# directories to ignore when looking for source files.
31+
exclude_patterns = ["_build"]
32+
33+
# The name of the Pygments (syntax highlighting) style to use.
34+
pygments_style = "sphinx"
35+
36+
# -- Options for HTML output -------------------------------------------------
37+
38+
# The theme to use for HTML and HTML Help pages.
1339
html_theme = "furo"
40+
41+
# Add any paths that contain custom static files (such as style sheets) here,
42+
# relative to this directory. They are copied after the builtin static files,
43+
# so a file named "default.css" will overwrite the builtin "default.css".
44+
html_static_path = ["_static"]
45+
46+
# -- Extension configuration -------------------------------------------------
47+
48+
# Napoleon settings
49+
napoleon_google_docstring = True
50+
napoleon_numpy_docstring = False
51+
napoleon_include_init_with_doc = False
52+
napoleon_include_private_with_doc = False
53+
napoleon_include_special_with_doc = True
54+
napoleon_use_admonition_for_examples = False
55+
napoleon_use_admonition_for_notes = False
56+
napoleon_use_admonition_for_references = False
57+
napoleon_use_ivar = False
58+
napoleon_use_param = True
59+
napoleon_use_rtype = True
60+
napoleon_preprocess_types = False
61+
napoleon_type_aliases = None
62+
napoleon_attr_annotations = True
63+
64+
# Autodoc settings
65+
autodoc_default_options = {
66+
"members": True,
67+
"member-order": "bysource",
68+
"special-members": "__init__",
69+
"undoc-members": True,
70+
"exclude-members": "__weakref__",
71+
}
72+
autodoc_typehints = "description"
73+
autodoc_mock_imports = ["django"] # Add any modules that might cause import errors during doc building
74+
75+
# Intersphinx settings
76+
intersphinx_mapping = {
77+
"python": ("https://docs.python.org/3", None),
78+
"django": ("https://docs.djangoproject.com/en/stable/", "https://docs.djangoproject.com/en/stable/_objects/"),
79+
}
80+
81+
# MyST Parser settings
82+
myst_enable_extensions = [
83+
"amsmath",
84+
"colon_fence",
85+
"deflist",
86+
"dollarmath",
87+
"html_admonition",
88+
"html_image",
89+
"linkify",
90+
"replacements",
91+
"smartquotes",
92+
"substitution",
93+
"tasklist",
94+
]

‎docs/reference.md‎

Lines changed: 117 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,122 @@
1-
# Reference
1+
# API Reference
22

3-
## django_help
3+
This reference provides detailed information about the modules and classes in the django-help app.
4+
5+
## Models
6+
7+
```{eval-rst}
8+
.. automodule:: django_help.models
9+
:members:
10+
:undoc-members:
11+
:show-inheritance:
12+
```
13+
14+
## Views
15+
16+
```{eval-rst}
17+
.. automodule:: django_help.views
18+
:members:
19+
:undoc-members:
20+
:show-inheritance:
21+
```
22+
23+
## Forms
24+
25+
```{eval-rst}
26+
.. automodule:: django_help.forms
27+
:members:
28+
:undoc-members:
29+
:show-inheritance:
30+
```
31+
32+
## Admin
33+
34+
```{eval-rst}
35+
.. automodule:: django_help.admin
36+
:members:
37+
:undoc-members:
38+
:show-inheritance:
39+
```
40+
41+
## Utils
42+
43+
### Exporting
44+
45+
```{eval-rst}
46+
.. automodule:: django_help.utils.exporting
47+
:members:
48+
:undoc-members:
49+
:show-inheritance:
50+
```
51+
52+
### Importing
53+
54+
```{eval-rst}
55+
.. automodule:: django_help.utils.importing
56+
:members:
57+
:undoc-members:
58+
:show-inheritance:
59+
```
60+
61+
### Queryset
62+
63+
```{eval-rst}
64+
.. automodule:: django_help.utils.queryset
65+
:members:
66+
:undoc-members:
67+
:show-inheritance:
68+
```
69+
70+
### Regex
71+
72+
```{eval-rst}
73+
.. automodule:: django_help.utils.regex
74+
:members:
75+
:undoc-members:
76+
:show-inheritance:
77+
```
78+
79+
### Validation
80+
81+
```{eval-rst}
82+
.. automodule:: django_help.utils.validation
83+
:members:
84+
:undoc-members:
85+
:show-inheritance:
86+
```
87+
88+
## Template Tags
89+
90+
```{eval-rst}
91+
.. automodule:: django_help.templatetags.django_help_tags
92+
:members:
93+
:undoc-members:
94+
:show-inheritance:
95+
```
96+
97+
## App Settings
98+
99+
```{eval-rst}
100+
.. automodule:: django_help.app_settings
101+
:members:
102+
:undoc-members:
103+
:show-inheritance:
104+
```
105+
106+
## Choices
107+
108+
```{eval-rst}
109+
.. automodule:: django_help.choices
110+
:members:
111+
:undoc-members:
112+
:show-inheritance:
113+
```
114+
115+
## URLs
4116

5117
```{eval-rst}
6-
.. automodule:: django_help
118+
.. automodule:: django_help.urls
7119
:members:
120+
:undoc-members:
121+
:show-inheritance:
8122
```

‎docs/requirements.txt‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,15 @@
1-
furo==2024.8.6
2-
sphinx==8.0.2
3-
sphinx-click==6.0.0
4-
myst-parser==4.0.0
1+
# Documentation dependencies
2+
Sphinx==7.1.2
3+
sphinx-rtd-theme==2.0.0
4+
sphinx-click==5.1.0
5+
myst-parser==2.0.0
6+
furo==2024.1.29
7+
8+
# Django and related packages (for autodoc)
9+
Django==5.0.2
10+
django-markdownx==4.0.7
11+
django-translated-fields==0.13.0
12+
django-taggit==6.0.0
13+
python-frontmatter==1.1.0
14+
django-crispy-forms==2.1
15+
crispy-bootstrap5==2024.2

‎docs/terminology.md‎

Lines changed: 46 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,51 @@
11
# Terminology and Definitions
22

3-
## Topic 1
3+
## App-specific Terms
44

5-
Content
5+
### Article
6+
An individual help content item, typically containing explanations, instructions, or information on a specific topic.
67

7-
## Topic 2
8+
### Category
9+
A grouping mechanism for organizing articles into related topics or sections.
810

9-
Content
11+
### Tag
12+
A label or keyword associated with one or more articles, used for classification and easier searching.
13+
14+
### Slug
15+
A URL-friendly version of a text, typically used in web addresses. For example, "how-to-reset-password" might be the slug for an article titled "How to Reset Your Password".
16+
17+
### Intended Entity Type
18+
A classification system used in django-help to specify whether an article or category is intended for a specific type of user or organization (e.g., individual, business, any).
19+
20+
### Relevant Path
21+
A URL path associated with an article, used to provide context-sensitive help based on the user's current location in the application.
22+
23+
### Highlighted Article
24+
An article marked as particularly important or featured, typically given prominence in the user interface.
25+
26+
### Public Article
27+
An article that is visible to all users. Non-public articles may have restricted visibility based on user permissions.
28+
29+
## Multi-language Support
30+
31+
### Translated Field
32+
A field in the database that stores content in multiple languages. In django-help, this is implemented using the django-translated-fields package.
33+
34+
### Language Code
35+
A short string identifying a specific language, typically following the ISO 639-1 standard (e.g., "en" for English, "es" for Spanish).
36+
37+
## Content Management
38+
39+
### Markdown
40+
A lightweight markup language used for formatting text. django-help uses Markdown for writing and storing article content.
41+
42+
### Frontmatter
43+
Metadata at the beginning of a Markdown file, typically written in YAML format. It's used to store additional information about an article, such as its title, tags, and other metadata.
44+
45+
## User Interface
46+
47+
### Modal
48+
A dialog box or popup window that appears on top of the current page. In django-help, modals are used to display article content without navigating away from the current page.
49+
50+
### HTMX
51+
A JavaScript library that allows you to access AJAX, CSS Transitions, WebSockets and Server Sent Events directly in HTML, without writing JavaScript. django-help uses HTMX for dynamic content loading.

0 commit comments

Comments
 (0)