After scouring back and forth the world wide web looking for who's content to devour it came to my notice that this content is the first of it's kind so I would first like to give a special shoutout to my Mom, my Dad 😭😭😭.
So to kickoff, i would start by highlighting the steps to take to get it done. (You know like begin with the end in mind)
- Create Django Project
- Install MkDocs & Build Documentation Folder
- Include Documentation Folder in
STATICFILES_DIRS - Register Documentation Folder for Template Rendering
- Setup Url Configuration for public visibility
- Setup MKDocs Configuration
- Insert Static Blocks in HTML File for Static File Management
Build your app...
Create Django Project
django-admin startproject google_docx
cd google_docx/
python3 -m venv env
source env/bin/activate
- Install MkDocs & Build Documentation Folder
pip install mkdocs
mkdocs new docs
cd docs
mkdocs build
And now to take a breather before we continue, feel free to go gossip with caroline at the coffee corner, hopefully it doesn't come back to bite you.
Done with the talk? Let's continue then
Below is currently the file structure of the documentation.
docs/
├── docs
│ └── index.md
├── mkdocs.yml
└── site
├── 404.html
├── css
│ ├── base.css
│ ├── bootstrap.min.css
│ ├── bootstrap.min.css.map
│ ├── brands.min.css
│ ├── fontawesome.min.css
│ ├── solid.min.css
│ └── v4-font-face.min.css
├── img
│ ├── favicon.ico
│ └── grid.png
├── index.html
├── js
│ ├── base.js
│ ├── bootstrap.bundle.min.js
│ ├── bootstrap.bundle.min.js.map
│ └── darkmode.js
├── search
│ ├── lunr.js
│ ├── main.js
│ ├── search_index.json
│ └── worker.js
├── sitemap.xml
├── sitemap.xml.gz
└── webfonts
├── fa-brands-400.ttf
├── fa-brands-400.woff2
├── fa-regular-400.ttf
├── fa-regular-400.woff2
├── fa-solid-900.ttf
├── fa-solid-900.woff2
├── fa-v4compatibility.ttf
└── fa-v4compatibility.woff2
google_docx/
├── asgi.py
├── __init__.py
├── settings.py
├── urls.py
└── wsgi.py
So to proceed, we would be heading to the next step.....
- Include Documentation Folder in
STATICFILES_DIRS& Register Documentation Folder for Template Rendering
Update the following in the settings.py file
STATIC_URL = 'static/'
STATIC_ROOT = os.path.join(BASE_DIR, STATIC_URL)
STATICFILES_DIRS = [
BASE_DIR / "docs/site", # mkdocs static directory
]
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': [os.path.join(BASE_DIR, 'docs/site')], # register directory for HTML template rendering
'APP_DIRS': True,
'OPTIONS': {
'context_processors': [
'django.template.context_processors.debug',
'django.template.context_processors.request',
'django.contrib.auth.context_processors.auth',
'django.contrib.messages.context_processors.messages',
],
},
},
]
- Setup
urls.pyConfiguration for public visibility
from django.contrib import admin
from django.urls import path
from django.views.generic import TemplateView
urlpatterns = [
path('admin/', admin.site.urls),
path('docs/', TemplateView.as_view(template_name="index.html")),
]
- Setup MKDocs Configuration
Update the mkdocs.yml file
site_name: Google Docx Documentation # Project Doc Name
site_dir: site
site_url: http://127.0.0.1:8000/docs
run the mkdocs build command
mkdocs build
- Insert Static Blocks in HTML File for Static File Management
NB:_ mkdocs by default generates index.html but django can only load static files like css and js with {% load static %} in html files. So keep in mind that when you update the document and build you would have to rerun this process._
<!DOCTYPE html>
<html lang="en" data-bs-theme="light">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="None">
{% load static %}
<link rel="canonical" href="http://127.0.0.1:8003/docs/">
<link rel="shortcut icon" href="{% static 'img/favicon.ico' %}">
<title>Google Docx Documentation</title>
<link href="{% static 'css/bootstrap.min.css' %}" rel="stylesheet">
<link href="{% static 'css/fontawesome.min.css' %}" rel="stylesheet">
<link href="{% static 'css/brands.min.css' %}" rel="stylesheet">
<link href="{% static 'css/solid.min.css' %}" rel="stylesheet">
<link href="{% static 'css/v4-font-face.min.css' %}" rel="stylesheet">
<link href="{% static 'css/base.css' %}" rel="stylesheet">
<link id="hljs-light" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css" >
<link id="hljs-dark" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github-dark.min.css" disabled>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min.js"></script>
<script>hljs.highlightAll();</script>
</head>
<script src="{% static 'js/bootstrap.bundle.min.js' %}"></script>
<script>
var base_url = ".",
shortcuts = {"help": 191, "next": 78, "previous": 80, "search": 83};
</script>
<script src="{% static 'js/base.js' %}"></script>
<script src="{% static 'search/main.js' %}"></script>
The final outcome as you'll see below that it's up and running and the code can be found in django_mkdocs
Thanks for your attention so far and would love you to know i'm open to feedback and collaboration.
Top comments (0)