Merge pull request #150 from pydanny/add-mkdocs-include

Add mkdocs include so README is the index
pydanny · Oct 30, 2023 · d8de597 · d8de597
2 parents 071032e + b402622
commit d8de597
Show file tree

Hide file tree

Showing 6 changed files with 31 additions and 47 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -6,10 +6,7 @@ build:
     python: "3.10"
   jobs:
     pre_build:
-      # Generate the Sphinx configuration for this Jupyter Book so it builds.
-      - "pip install -r docs/requirements.txt"
-      - "pip install ."
-      - pip install "mkdocs-material[imaging]"
+      - "pip install '.[docs]'"
       - "mkdocs build"
 
 mkdocs:

diff --git a/README.md b/README.md
@@ -14,12 +14,16 @@ Full documentation available at [dj-notebook](https://dj-notebook.readthedocs.io
 
 ## Features
 
-- Easy ipython notebooks with Django
-- Built-in integration with the imported objects from django-extensions
+The ever-growing list of features:
+
+- Easy Jupyter notebooks with Django
+- Built-in integration with the imported objects from django-extensions `shell_plus`
+- Saves the state between sessions so you don't need to remember what you did
 - Inheritance diagrams on any object, including ORM models
 - Converts any Django QuerySet to Pandas Dataframe
-- Handy function for displaying mermaid charts in 
+- Handy function for displaying MermaidJS charts 
 - Generates visual maps of model relations
+- Works in the browser, VSCode, PyCharm, Emacs, Vim, and more!
 
 ## Installation
 
@@ -83,18 +87,28 @@ Generates this image
 
 <img src="https://mermaid.ink/img/Y2xhc3NEaWFncmFtCiAgY2xhc3MgZGphbmdvX2NvbnRyaWJfYXV0aF9tb2RlbHNfVXNlclsiZGphbmdvLmNvbnRyaWIuYXV0aC5tb2RlbHM6OlVzZXIiXQogIGRqYW5nb19kYl9tb2RlbHNfdXRpbHNfQWx0ZXJzRGF0YSA8fC0tIGRqYW5nb19kYl9tb2RlbHNfYmFzZV9Nb2RlbAogIGNsYXNzIGRqYW5nb19kYl9tb2RlbHNfdXRpbHNfQWx0ZXJzRGF0YVsiZGphbmdvLmRiLm1vZGVscy51dGlsczo6QWx0ZXJzRGF0YSJdCiAgZGphbmdvX2NvbnRyaWJfYXV0aF9iYXNlX3VzZXJfQWJzdHJhY3RCYXNlVXNlciA8fC0tIGRqYW5nb19jb250cmliX2F1dGhfbW9kZWxzX0Fic3RyYWN0VXNlcgogIGRqYW5nb19jb250cmliX2F1dGhfbW9kZWxzX1Blcm1pc3Npb25zTWl4aW4gPHwtLSBkamFuZ29fY29udHJpYl9hdXRoX21vZGVsc19BYnN0cmFjdFVzZXIKICBjbGFzcyBkamFuZ29fY29udHJpYl9hdXRoX21vZGVsc19BYnN0cmFjdFVzZXJbImRqYW5nby5jb250cmliLmF1dGgubW9kZWxzOjpBYnN0cmFjdFVzZXIiXQogIGNsYXNzIGRqYW5nb19kYl9tb2RlbHNfYmFzZV9Nb2RlbFsiZGphbmdvLmRiLm1vZGVscy5iYXNlOjpNb2RlbCJdCiAgY2xhc3MgZGphbmdvX2NvbnRyaWJfYXV0aF9iYXNlX3VzZXJfQWJzdHJhY3RCYXNlVXNlclsiZGphbmdvLmNvbnRyaWIuYXV0aC5iYXNlX3VzZXI6OkFic3RyYWN0QmFzZVVzZXIiXQogIGRqYW5nb19kYl9tb2RlbHNfYmFzZV9Nb2RlbCA8fC0tIGRqYW5nb19jb250cmliX2F1dGhfYmFzZV91c2VyX0Fic3RyYWN0QmFzZVVzZXIKICBkamFuZ29fZGJfbW9kZWxzX2Jhc2VfTW9kZWwgPHwtLSBkamFuZ29fY29udHJpYl9hdXRoX21vZGVsc19QZXJtaXNzaW9uc01peGluCiAgZGphbmdvX2NvbnRyaWJfYXV0aF9tb2RlbHNfQWJzdHJhY3RVc2VyIDx8LS0gZGphbmdvX2NvbnRyaWJfYXV0aF9tb2RlbHNfVXNlcgogIGNsYXNzIGRqYW5nb19jb250cmliX2F1dGhfbW9kZWxzX1Blcm1pc3Npb25zTWl4aW5bImRqYW5nby5jb250cmliLmF1dGgubW9kZWxzOjpQZXJtaXNzaW9uc01peGluIl0="/>
 
+Here's another useful diagram:
+
+```python
+plus.model_graph(plus.User)
+```
+
+<image src="https://mermaid.ink/img/Zmxvd2NoYXJ0IFRECiAgTG9nRW50cnkgLS0tIFVzZXIKICBVc2VyIC0tLSBBYnN0cmFjdFVzZXIKICBVc2VyIC0tLSBHcm91cAogIFVzZXIgLS0tIFBlcm1pc3Npb24K"/>
+
 ## QuerySet to Dataframe
 
+Want to convert a Django query to a Pandas Dataframe? We got you covered.
+
 ```python
 plus.read_frame(plus.User.objects.all())
 ```
 
-## Check out the official documentation for more things you can do!
+## More things you can do!
 
 [dj-notebook official documentation](https://dj-notebook.readthedocs.io/)
 
 
-# Contributors
+## Contributors
 
 <!-- readme: contributors -start -->
 <table>

diff --git a/docs/index.md b/docs/index.md
@@ -1,36 +1,7 @@
 # Home
 
-![dj-notebook logo](img/dj-notebook-logo.png)
-
-_Django + shell_plus + Jupyter notebooks made easy_
-
-A Jupyter notebook with access to objects from the Django ORM is a powerful tool to introspect data and run ad-hoc queries.
-
-## Features
-
-The ever-growing list of features:
-
-- Easy ipython notebooks with Django
-- Built-in integration with the imported objects from django-extensions
-- Inheritance diagrams on any object, including ORM models
-- Converts any Django QuerySet to Pandas Dataframe
-- Handy function for displaying mermaid charts in 
-- Generates visual maps of model relations
-
-## Examples
-
-```python
-from dj_notebook import activate
-plus = activate()
-plus.User.objects.all()
-```
-
-```
-<QuerySet [<User: Audrey>, <User: Daniel>]>
-```
-
-!!! tip "Full Usage"
-
-    Learn how to use all the awesome features of dj-notebook in the [usage page](./usage)!
-
-
+{%
+   include-markdown "../README.md"
+   start="<!--intro-start-->"
+   end="<!--intro-end-->"
+%}
diff --git a/docs/requirements.txt b/docs/requirements.txt
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -22,10 +22,12 @@ plugins:
           remove_tag_config:
               remove_input_tags:
                   - hide_code
+    - include-markdown:
+          start: <!--start-->
+          end: <!--end-->                    
     - search
     - social    
 
-
 nav:
   - Introduction: index.md
   - Installation:

diff --git a/pyproject.toml b/pyproject.toml
@@ -54,7 +54,9 @@ test = [
 ]
 docs = [
   "mkdocs-material",
-  "mkdocs-jupyter"
+  "mkdocs-jupyter",
+  "mkdocs-material[imaging]",
+  "mkdocs-include-markdown-plugin"  
 ]
 
 [project.urls]