Merge pull request #7 from encode/cleanup

Clean up

Author: lovelydinosaur

README.md

@@ -0,0 +1,33 @@
+# MkDocs
+
+MkDocs is a smart, simple, website design tool.
+
+## Installation
+
+Install the `mkdocs` command line tool...
+
+```shell
+$ pip install mkdocs
+```
+
+## Getting started
+
+1. Create a `README.md` page.
+2. Run `mkdocs serve` to view your documentation in a browser.
+3. Run `mkdocs build` to build a static website ready to host.
+
+MkDocs supports [GitHub Flavored Markdown](writing.md) for page authoring.
+
+## Adding pages
+
+1. Create additional markdown pages.
+2. Use markdown interlinking between pages.
+3. Create a `mkdocs.toml` config file to define the site navigation.
+
+## Custom styling
+
+1. Create a `templates/base.html` file to customise the layout.
+2. Create a `css/base.css` file to override the default styles.
+3. Create a `js/base.css` file to override the default scripts.
+
+Simple [styling adaptations](styling.md) include customising the colour scheme, the typography, or choosing the code highlighting style.

docs/configuration.md

@@ -0,0 +1,84 @@
+# Configuration
+
+Site navigation and other configuration is defined in a `mkdocs.toml` file.
+
+```toml
+[mkdocs]
+nav = [
+    {title="Introduction", path="index.md"},
+    {title="Writing Markdown", path="writing.md"},
+    {title="Site Navigation", path="navigation.md"},
+    {title="HTML Styling", path="styling.md"}
+]
+```
+
+Navigation can include subsections...
+
+```toml
+[mkdocs]
+nav = [
+    {title="Introduction", path="README.md"},
+    {title="Guides", children=[
+        {title="Writing Markdown", path="writing.md"},
+        {title="Site Navigation", path="navigation.md"},
+        {title="HTML Styling", path="styling.md"}
+    ]}
+]
+```
+
+### Loaders
+
+Loaders determine where documentation resources are collected from.
+
+```toml
+loaders = [
+    {type="directory", dir="docs"},
+    {type="package", pkg="mkdocs.theme"}
+]
+```
+
+Customise this to load a different theme, from a ZIP archive...
+
+```toml
+loaders = [
+    {type="directory", dir="docs"},
+    {type="url", url="https://www.example.com/theme.zip"}
+]
+```
+
+Or from a GitHub repo...
+
+```toml
+loaders = [
+    {type="directory", dir="docs"},
+    {type="github", url="mkdocs/default"}
+]
+```
+
+<!--
+### Markdown
+
+The derault set of extensions are geared towards GitHub Flavored Markdown.
+
+```toml
+[markdown]
+extensions = {...}
+config = {...}
+```
+
+### Resources
+
+Resources include markdown pages, static media, and HTML templates.
+
+* `pages`      - `*.md`
+* `statics`    - `*` 
+* `templates`  - `templates/*`
+
+### Commands
+
+The command line tool allows you to work with mkdocs locally,
+or to build and host your sites on a provider of your choosing.
+
+* `mkdocs serve`
+* `mkdocs build`
+-->

docs/index.md

@@ -1,30 +1,28 @@
 # MkDocs
 
-MkDocs is a smart, simple website design tool using [Markdown](writing.md), [templated HTML](styling.md#templates), and static [media files](styling.md#media).
+MkDocs is a smart, simple, website design tool.
 
 ## Installation
 
-Install the mkdocs command line tool...
+Install the `mkdocs` command line tool...
 
 ```shell
 $ pip install mkdocs
 ```
 
 ## Getting started
 
-1. Create a `README.md` file, and get authoring.
+1. Create a `README.md` page.
 2. Run `mkdocs serve` to view your documentation in a browser.
 3. Run `mkdocs build` to build a static website ready to host.
 
 MkDocs supports [GitHub Flavored Markdown](writing.md) for page authoring.
 
 ## Adding pages
 
-1. Create other markdown files, such as `CONTRIBUTING.md`.
-2. Link between your documents, eg. `See the [contributing](CONTRIBUTING.md) page for more details`.
-3. Create a `mkdocs.json` config file to add site navigation.
-
-Sites can be single page, multipage, or deeply nested. Just use regular interlinking between your markdown documents, with `mkdocs.json` to define an overall [site layout](navigation.md).
+1. Create additional markdown pages.
+2. Use markdown interlinking between pages.
+3. Create a `mkdocs.toml` config file to define the site navigation.
 
 ## Custom styling
 

docs/navigation.md

@@ -37,7 +37,7 @@ Back to the [homepage](../index.md).
 
 You can include site-wide navigation by using the `mkdocs.toml` configuration.
 
-```
+```toml
 [mkdocs]
 version = 2
 
@@ -56,7 +56,7 @@ This allows the theme to display navigation controls, as well as including `←
 
 The navigation configuration can also include nested elements.
 
-```
+```toml
 [mkdocs]
 version = 2
 

docs/styling.md

@@ -4,7 +4,7 @@ Styling is handled with HTML templating and regular web design.
 
 ## Templates
 
-Anything in the `/templates/` directory is treated as a [Jinja template](https://jinja.palletsprojects.com/en/stable/templates/), and is used to render pages, rather than being served directly. You can override templates locally and adapt them to make layout changes.
+Anything in the `/templates/` directory is treated as a [Jinja template](https://jinja.palletsprojects.com/en/stable/templates/), and is used to render markdown pages. You can override templates locally and adapt them to make layout changes.
 
 The base template for rendering markdown pages is **`templates/base.html`**. 
 

src/mkdocs/mkdocs.py

@@ -1,5 +1,7 @@
+# import io
 import pathlib
 import typing
+# import zipfile
 
 import httpx
 import jinja2
@@ -110,6 +112,32 @@ def __repr__(self):
         return f'<Package {self._pkg!r}>'
 
 
+# class ZipURL(Handler):
+#     def __init__(self, url: str) -> None:
+#         self._url = url
+#         self._topdir = ''
+
+#     def load_paths(self) -> list[pathlib.Path]:
+#         r = httpx.get(self._url)
+#         b = io.BytesIO(r.body)
+#         with zipfile.ZipFile(b, 'r') as zip_ref:
+#             names = [
+#                 pathlib.PosixPath(name) for name in zip_ref.namelist()
+#                 if not name.endswith('/')
+#             ]
+#             if len(set([name.parts[0] for name in names])) == 1:
+#                 self._topdir = names[0].parts[0]
+#                 names = [pathlib.PosixPath(*name.parts[1:]) for name in names]
+#         return names
+
+#     def read(self, path: pathlib.Path) -> bytes:
+#         r = httpx.get(self._url)
+#         b = io.BytesIO(r.body)
+#         with zipfile.ZipFile(b, 'r') as zip_ref:
+#             path = f"{self._topdir}/{path}" if self._topdir else path
+#             with zip_ref.open(str(path)) as f:
+#                 return f.read()
+
 # Resources & Templates...
 
 class Resource:
@@ -157,7 +185,9 @@ def get_source(self, environment, template: str):
 
 
 class MkDocs:
-    def __init__(self):
+    def __init__(self, config: str = '', theme: str = ''):
+        self.config = config or 'mkdocs.toml'
+        self.theme = theme
         self.content_types = {
             ".json": "application/json",
             ".js": "application/javascript",
@@ -175,7 +205,7 @@ def path_to_url(self, path: pathlib.Path) -> str:
             # 'index.html' -> '/'
             return pathlib.Path('/').joinpath(path).parent.as_posix().lower()
         if path.name.lower() in ('readme.md', 'index.md', 'index.html'):
-            # 'topics/README.md' -> '/'
+            # 'topics/README.md' -> '/topics/'
             # 'topics/index.html' -> '/topics/'
             return pathlib.Path('/').joinpath(path).parent.as_posix().lower() + '/'
         elif path.suffix == '.md':
@@ -196,12 +226,12 @@ def load_config(self, filename: str) -> dict:
         except tomllib.TOMLDecodeError as exc:
             raise ConfigError(f"Invalid TOML in config '{filename}'\n{exc}")
 
-        if 'mkdocs' not in config:
-            raise ConfigError(f"Config '{filename}' missing '[mkdocs]' section.")
-        if 'version' not in config['mkdocs']:
-            raise ConfigError(f"Config '{filename}' missing 'version=...' in '[mkdocs]' section.")
-        if config['mkdocs']['version'] != 2:
-            raise ConfigError(f"Config '{filename}' expected 'version=2' in '[mkdocs]' section.")
+        # if 'mkdocs' not in config:
+        #     raise ConfigError(f"Config '{filename}' missing '[mkdocs]' section.")
+        # if 'version' not in config['mkdocs']:
+        #     raise ConfigError(f"Config '{filename}' missing 'version=...' in '[mkdocs]' section.")
+        # if config['mkdocs']['version'] != 2:
+        #     raise ConfigError(f"Config '{filename}' expected 'version=2' in '[mkdocs]' section.")
 
         default = {
             'mkdocs': {
@@ -211,19 +241,13 @@ def load_config(self, filename: str) -> dict:
                 'title': 'MkDocs',
                 'favicon': '📘',
                 'nav': [],
-                # 'nav': [
-                #     {'title': 'Introduction', 'path': 'README.md'},
-                #     {'title': 'Writing content', 'path': 'writing.md'},
-                #     {'title': 'Site navigation', 'path': 'navigation.md'},
-                #     {'title': 'Themes & styling', 'path': 'styling.md'},
-                # ],
             },
             # 'handlers': [
             #     {'type': 'mkdocs.Package', 'pkg': 'mkdocs:theme'}
             #     {'type': 'mkdocs.Directory', 'dir': 'docs'}
             # ],
             'markdown': {
-                'extensions': {
+                'extensions': [
                     'fenced_code',
                     'footnotes',
                     'tables',
@@ -233,7 +257,7 @@ def load_config(self, filename: str) -> dict:
                     'mkdocs.rewrite_urls',
                     'mkdocs.short_codes',
                     'mkdocs.strike_thru',
-                },
+                ],
                 'configs': {
                     'footnotes': {'BACKLINK_TITLE': ''},
                     'toc': {'anchorlink': True, 'marker': ''}
@@ -246,6 +270,11 @@ def load_config(self, filename: str) -> dict:
         return Config(config, filename=filename)
 
     def load_handlers(self, config: dict) -> list[Handler]:
+        if not pathlib.Path('docs').is_dir():
+            return [
+                Package('mkdocs'),
+                Directory('.'),
+            ]
         return [
             Package('mkdocs'),
             Directory('docs'),

src/mkdocs/theme/templates/base.html

@@ -2,7 +2,7 @@
     <head>
         <meta charset="utf-8">
         <meta name="viewport" content="width=device-width, initial-scale=1.0">
-        <title>{{ config['site']['title'] }}</title>
+        <title>{{ config.site.title }}</title>
         <link rel="icon" href="data:image/svg+xml,{% include 'favicon.svg' %}">
         <link rel="stylesheet" href="/css/highlightjs.min.css">
         <link rel="stylesheet" href="/css/highlightjs-copy.min.css">

src/mkdocs/theme/templates/pagination.html

@@ -1,10 +1,10 @@
 {% if page.previous or page.next %}
 <div class="pagination">
     {% if page.previous %}
-    <a class="previous" href="{{ page.previous['url']}}">← {{ page.previous['title']}}</a>
+    <a class="previous" href="{{ page.previous.url }}">← {{ page.previous.title }}</a>
     {% endif %}
     {% if page.next %}
-    <a class="next" href="{{ page.next['url']}}">{{ page.next['title']}} →</a>
+    <a class="next" href="{{ page.next.url }}">{{ page.next.title }} →</a>
     {% endif %}
 </div>
 {% endif %}