docsforge 9.7.6__tar.gz → 10.1.0__tar.gz

docsforge-10.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: docsforge
+Version: 10.1.0
+Summary: Self-contained unified documentation engine with Material theme.
+Project-URL: Documentation, https://docsforge.readthedocs.io/
+Project-URL: Source, https://github.com/docsforge/docsforge
+Project-URL: Issues, https://github.com/docsforge/docsforge/issues
+Author: DocsForge Contributors
+License-Expression: LGPL-3.0-or-later
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.10
+Requires-Dist: babel>=2.9.0
+Requires-Dist: backrefs>=5.0
+Requires-Dist: click>=7.0
+Requires-Dist: colorama>=0.4
+Requires-Dist: ghp-import>=1.0
+Requires-Dist: jinja2>=2.11.1
+Requires-Dist: markdown>=3.3.6
+Requires-Dist: markupsafe>=2.0.1
+Requires-Dist: mergedeep>=1.3.4
+Requires-Dist: packaging>=20.5
+Requires-Dist: paginate>=0.5
+Requires-Dist: pathspec>=0.11.1
+Requires-Dist: platformdirs>=2.2.0
+Requires-Dist: pygments>=2.16
+Requires-Dist: pymdown-extensions>=10.0
+Requires-Dist: pyyaml-env-tag>=0.1
+Requires-Dist: pyyaml>=5.1
+Requires-Dist: requests>=2.27
+Requires-Dist: watchdog>=2.0
+Provides-Extra: imaging
+Requires-Dist: cairosvg>=2.6; extra == 'imaging'
+Requires-Dist: pillow>=10.2; extra == 'imaging'
+Description-Content-Type: text/markdown
+
+# DocsForge
+
+> **One package. One command. Beautiful docs.**
+
+[![PyPI](https://img.shields.io/pypi/v/docsforge)](https://pypi.org/project/docsforge/)
+[![Docs](https://img.shields.io/badge/docs-online-blue)](https://qqshi13.github.io/docsforge-docs/)
+[![License](https://img.shields.io/badge/license-LGPL%20v3-blue.svg)](LICENSE)
+
+DocsForge unifies the [ProperDocs](https://github.com/properdocs/properdocs) documentation engine and the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme into a single, installable package. You write content. DocsForge handles the engine, the theme, and the plugins.
+
+📖 **[Documentation](https://qqshi13.github.io/docsforge-docs/)** | 📦 **[PyPI](https://pypi.org/project/docsforge/)** | 🐙 **[GitHub](https://github.com/QQSHI13/docsforge)**
+
+---
+
+## Vision
+
+MkDocs is effectively unmaintained. Material for MkDocs is in maintenance mode. [ProperDocs](https://github.com/properdocs/properdocs) is the actively maintained fork of MkDocs that keeps the ecosystem alive.
+
+DocsForge makes the successor ecosystem effortless:
+
+- **One `pip install`** gets you the engine + theme + recommended plugins.
+- **One config file** (`docsforge.yml`) with no boilerplate `plugins:` list.
+- **Backward compatible** — existing `mkdocs.yml` files work unchanged.
+- **Plugin system stays alive** — we just auto-register Material plugins so you never write a `plugins:` section.
+
+---
+
+## Installation
+
+```bash
+pip install docsforge
+```
+
+That's it. ProperDocs, Material for MkDocs, and common plugins are installed together.
+
+---
+
+## Quick Start
+
+### 1. Create a new site
+
+```bash
+docsforge new my-docs
+cd my-docs
+```
+
+This scaffolds:
+
+```
+my-docs/
+├── docsforge.yml          # Config with Material theme pre-selected
+└── docs/
+    └── index.md           # Starter page
+```
+
+### 2. Preview locally
+
+```bash
+docsforge serve
+```
+
+Material plugins (search, tags, etc.) are **auto-registered** — no `plugins:` list needed.
+
+### 3. Build for production
+
+```bash
+docsforge build
+```
+
+### 4. Deploy to GitHub Pages
+
+```bash
+docsforge gh-deploy
+```
+
+---
+
+## Config File
+
+DocsForge looks for config in this priority:
+
+1. `docsforge.yml` / `docsforge.yaml` ← **preferred**
+2. `properdocs.yml` / `properdocs.yaml`
+3. `mkdocs.yml` / `mkdocs.yaml` ← legacy fallback
+
+### Minimal `docsforge.yml`
+
+```yaml
+site_name: My Documentation
+site_url: https://example.com/
+repo_url: https://github.com/username/repo
+
+# Theme defaults to "material" — you can omit this entirely.
+theme:
+  name: material
+
+# No plugins: section needed — search, tags, blog, privacy, social
+# are auto-registered based on what you have installed.
+```
+
+### Advanced — override auto-plugins
+
+If you define `plugins:` yourself, DocsForge **merges** rather than overwrites:
+
+```yaml
+site_name: My Docs
+
+plugins:
+  search:
+    lang: en
+  tags:
+    tags_file: tags.md
+  # blog, privacy, social are still auto-registered if available
+```
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `docsforge new <name>` | Scaffold a new project |
+| `docsforge serve` | Live-reload dev server |
+| `docsforge build` | Static site build |
+| `docsforge gh-deploy` | Deploy to GitHub Pages |
+
+All commands accept `-f / --config-file` to override config discovery.
+
+---
+
+## Architecture
+
+```
+docsforge/                    # Unified package
+├── __init__.py
+├── cli.py                    # `docsforge` command (wraps properdocs)
+├── config.py                 # Unified config loader
+├── plugins/
+│   └── auto_register.py      # Pre-loads Material plugins
+├── engine/                   # ProperDocs core (git subtree)
+│   └── (properdocs source)
+└── themes/                   # Material for MkDocs (git subtree)
+    └── (mkdocs-material source)
+```
+
+**Key decisions:**
+
+1. **Keep the plugin system alive.** Material's plugins (blog, tags, privacy, social, search) are powerful. We auto-register them instead of rewriting them.
+2. **ProperDocs dual entrypoints.** ProperDocs already supports both `mkdocs.*` and `properdocs.*` entrypoints, so Material works without code changes.
+3. **Unified CLI, not a fork.** We wrap ProperDocs commands; we don't fork the engine.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full design record.
+
+---
+
+## License
+
+GPL-3.0-or-later — same as ProperDocs.
+
+---
+
+*DocsForge is a repackaging project, not a fork. It keeps the MkDocs/ProperDocs ecosystem moving forward while the upstreams navigate their maintenance transitions.*

docsforge-10.1.0/README.md

@@ -0,0 +1,162 @@
+# DocsForge
+
+> **One package. One command. Beautiful docs.**
+
+[![PyPI](https://img.shields.io/pypi/v/docsforge)](https://pypi.org/project/docsforge/)
+[![Docs](https://img.shields.io/badge/docs-online-blue)](https://qqshi13.github.io/docsforge-docs/)
+[![License](https://img.shields.io/badge/license-LGPL%20v3-blue.svg)](LICENSE)
+
+DocsForge unifies the [ProperDocs](https://github.com/properdocs/properdocs) documentation engine and the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme into a single, installable package. You write content. DocsForge handles the engine, the theme, and the plugins.
+
+📖 **[Documentation](https://qqshi13.github.io/docsforge-docs/)** | 📦 **[PyPI](https://pypi.org/project/docsforge/)** | 🐙 **[GitHub](https://github.com/QQSHI13/docsforge)**
+
+---
+
+## Vision
+
+MkDocs is effectively unmaintained. Material for MkDocs is in maintenance mode. [ProperDocs](https://github.com/properdocs/properdocs) is the actively maintained fork of MkDocs that keeps the ecosystem alive.
+
+DocsForge makes the successor ecosystem effortless:
+
+- **One `pip install`** gets you the engine + theme + recommended plugins.
+- **One config file** (`docsforge.yml`) with no boilerplate `plugins:` list.
+- **Backward compatible** — existing `mkdocs.yml` files work unchanged.
+- **Plugin system stays alive** — we just auto-register Material plugins so you never write a `plugins:` section.
+
+---
+
+## Installation
+
+```bash
+pip install docsforge
+```
+
+That's it. ProperDocs, Material for MkDocs, and common plugins are installed together.
+
+---
+
+## Quick Start
+
+### 1. Create a new site
+
+```bash
+docsforge new my-docs
+cd my-docs
+```
+
+This scaffolds:
+
+```
+my-docs/
+├── docsforge.yml          # Config with Material theme pre-selected
+└── docs/
+    └── index.md           # Starter page
+```
+
+### 2. Preview locally
+
+```bash
+docsforge serve
+```
+
+Material plugins (search, tags, etc.) are **auto-registered** — no `plugins:` list needed.
+
+### 3. Build for production
+
+```bash
+docsforge build
+```
+
+### 4. Deploy to GitHub Pages
+
+```bash
+docsforge gh-deploy
+```
+
+---
+
+## Config File
+
+DocsForge looks for config in this priority:
+
+1. `docsforge.yml` / `docsforge.yaml` ← **preferred**
+2. `properdocs.yml` / `properdocs.yaml`
+3. `mkdocs.yml` / `mkdocs.yaml` ← legacy fallback
+
+### Minimal `docsforge.yml`
+
+```yaml
+site_name: My Documentation
+site_url: https://example.com/
+repo_url: https://github.com/username/repo
+
+# Theme defaults to "material" — you can omit this entirely.
+theme:
+  name: material
+
+# No plugins: section needed — search, tags, blog, privacy, social
+# are auto-registered based on what you have installed.
+```
+
+### Advanced — override auto-plugins
+
+If you define `plugins:` yourself, DocsForge **merges** rather than overwrites:
+
+```yaml
+site_name: My Docs
+
+plugins:
+  search:
+    lang: en
+  tags:
+    tags_file: tags.md
+  # blog, privacy, social are still auto-registered if available
+```
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `docsforge new <name>` | Scaffold a new project |
+| `docsforge serve` | Live-reload dev server |
+| `docsforge build` | Static site build |
+| `docsforge gh-deploy` | Deploy to GitHub Pages |
+
+All commands accept `-f / --config-file` to override config discovery.
+
+---
+
+## Architecture
+
+```
+docsforge/                    # Unified package
+├── __init__.py
+├── cli.py                    # `docsforge` command (wraps properdocs)
+├── config.py                 # Unified config loader
+├── plugins/
+│   └── auto_register.py      # Pre-loads Material plugins
+├── engine/                   # ProperDocs core (git subtree)
+│   └── (properdocs source)
+└── themes/                   # Material for MkDocs (git subtree)
+    └── (mkdocs-material source)
+```
+
+**Key decisions:**
+
+1. **Keep the plugin system alive.** Material's plugins (blog, tags, privacy, social, search) are powerful. We auto-register them instead of rewriting them.
+2. **ProperDocs dual entrypoints.** ProperDocs already supports both `mkdocs.*` and `properdocs.*` entrypoints, so Material works without code changes.
+3. **Unified CLI, not a fork.** We wrap ProperDocs commands; we don't fork the engine.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full design record.
+
+---
+
+## License
+
+GPL-3.0-or-later — same as ProperDocs.
+
+---
+
+*DocsForge is a repackaging project, not a fork. It keeps the MkDocs/ProperDocs ecosystem moving forward while the upstreams navigate their maintenance transitions.*

docsforge-10.1.0/docsforge/__init__.py

@@ -0,0 +1,11 @@
+"""DocsForge - Unified documentation engine with Material theme.
+
+DocsForge combines the ProperDocs build engine with the Material for MkDocs
+theme and plugins into a single, cohesive package.
+"""
+
+__version__ = "10.1.0"
+__prog_name__ = "docsforge"
+
+# Install vendor compatibility shims
+import docsforge._vendor_shims

docsforge-10.1.0/docsforge/_vendor/mkdocs/config/defaults.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+import logging
+from typing import IO, Dict, Mapping
+
+from docsforge._vendor.mkdocs.config import base
+from docsforge._vendor.mkdocs.config import config_options as c
+from docsforge._vendor.mkdocs.structure.pages import Page, _AbsoluteLinksValidationValue
+from docsforge._vendor.mkdocs.utils.yaml import get_yaml_loader, yaml_load
+
+
+class _LogLevel(c.OptionallyRequired[int]):
+    levels: Mapping[str, int] = {
+        "warn": logging.WARNING,
+        "info": logging.INFO,
+        "ignore": logging.DEBUG,
+    }
+
+    def run_validation(self, value: object) -> int:
+        if not isinstance(value, str):
+            raise base.ValidationError(f"Expected a string, but a {type(value)} was given.")
+        try:
+            return self.levels[value]
+        except KeyError:
+            raise base.ValidationError(f"Expected one of {list(self.levels)}, got {value!r}")
+
+
+class _AbsoluteLinksValidation(_LogLevel):
+    levels: Mapping[str, int] = {
+        **_LogLevel.levels,
+        "relative_to_docs": _AbsoluteLinksValidationValue.RELATIVE_TO_DOCS,
+    }
+
+
+# NOTE: The order here is important. During validation some config options
+# depend on others. So, if config option A depends on B, then A should be
+# listed higher in the schema.
+class MkDocsConfig(base.Config):
+    """The configuration of MkDocs itself (the root object of mkdocs.yml)."""
+
+    config_file_path: str = c.Type(str)  # type: ignore[assignment]
+    """The path to the mkdocs.yml config file. Can't be populated from the config."""
+
+    site_name = c.Type(str)
+    """The title to use for the documentation."""
+
+    nav = c.Optional(c.Nav())
+    """Defines the structure of the navigation."""
+    pages = c.Deprecated(removed=True, moved_to='nav')
+
+    exclude_docs = c.Optional(c.PathSpec())
+    """Gitignore-like patterns of files (relative to docs dir) to exclude from the site."""
+
+    draft_docs = c.Optional(c.PathSpec())
+    """Gitignore-like patterns of files (relative to docs dir) to mark as draft."""
+
+    not_in_nav = c.Optional(c.PathSpec())
+    """Gitignore-like patterns of files (relative to docs dir) that are not intended to be in the nav.
+
+    This marks doc files that are expected not to be in the nav, otherwise they will cause a log message
+    (see also `validation.nav.omitted_files`).
+    """
+
+    site_url = c.Optional(c.URL(is_dir=True))
+    """The full URL to where the documentation will be hosted."""
+
+    site_description = c.Optional(c.Type(str))
+    """A description for the documentation project that will be added to the
+    HTML meta tags."""
+    site_author = c.Optional(c.Type(str))
+    """The name of the author to add to the HTML meta tags."""
+
+    theme = c.Theme(default='mkdocs')
+    """The MkDocs theme for the documentation."""
+
+    docs_dir = c.DocsDir(default='docs', exists=True)
+    """The directory containing the documentation markdown."""
+
+    site_dir = c.SiteDir(default='site')
+    """The directory where the site will be built to"""
+
+    copyright = c.Optional(c.Type(str))
+    """A copyright notice to add to the footer of documentation."""
+
+    google_analytics = c.Deprecated(
+        message=(
+            'The configuration option {} has been deprecated and '
+            'will be removed in a future release of MkDocs. See the '
+            'options available on your theme for an alternative.'
+        ),
+        option_type=c.Type(list, length=2),
+    )
+    """set of values for Google analytics containing the account IO and domain
+    this should look like, ['UA-27795084-5', 'mkdocs.org']"""
+
+    dev_addr = c.IpAddress(default='127.0.0.1:8000')
+    """The address on which to serve the live reloading docs server."""
+
+    use_directory_urls = c.Type(bool, default=True)
+    """If `True`, use `<page_name>/index.html` style files with hyperlinks to
+    the directory. If `False`, use `<page_name>.html style file with
+    hyperlinks to the file.
+    True generates nicer URLs, but False is useful if browsing the output on
+    a filesystem."""
+
+    repo_url = c.Optional(c.URL())
+    """Specify a link to the project source repo to be included
+    in the documentation pages."""
+
+    repo_name = c.Optional(c.RepoName('repo_url'))
+    """A name to use for the link to the project source repo.
+    Default, If repo_url is unset then None, otherwise
+    "GitHub", "Bitbucket" or "GitLab" for known url or Hostname
+    for unknown urls."""
+
+    edit_uri_template = c.Optional(c.EditURITemplate('edit_uri'))
+    edit_uri = c.Optional(c.EditURI('repo_url'))
+    """Specify a URI to the docs dir in the project source repo, relative to the
+    repo_url. When set, a link directly to the page in the source repo will
+    be added to the generated HTML. If repo_url is not set also, this option
+    is ignored."""
+
+    extra_css = c.Type(list, default=[])
+    extra_javascript = c.ListOfItems(c.ExtraScript(), default=[])
+    """Specify which css or javascript files from the docs directory should be
+    additionally included in the site."""
+
+    extra_templates = c.Type(list, default=[])
+    """Similar to the above, but each template (HTML or XML) will be build with
+    Jinja2 and the global context."""
+
+    markdown_extensions = c.MarkdownExtensions(
+        builtins=['toc', 'tables', 'fenced_code'],
+        default=[
+            'admonition',
+            'footnotes',
+            'def_list',
+            'abbr',
+            'attr_list',
+            'md_in_html',
+            'meta',
+            'nl2br',
+            'sane_lists',
+            'wikilinks',
+            'pymdownx.arithmatex',
+            'pymdownx.b64',
+            'pymdownx.betterem',
+            'pymdownx.caret',
+            'pymdownx.critic',
+            'pymdownx.details',
+            'pymdownx.emoji',
+            'pymdownx.escapeall',
+            'pymdownx.extra',
+            'pymdownx.fancylists',
+            'pymdownx.highlight',
+            'pymdownx.inlinehilite',
+            'pymdownx.keys',
+            'pymdownx.magiclink',
+            'pymdownx.mark',
+            'pymdownx.pathconverter',
+            'pymdownx.progressbar',
+            'pymdownx.quotes',
+            'pymdownx.saneheaders',
+            'pymdownx.smartsymbols',
+            'pymdownx.snippets',
+            'pymdownx.striphtml',
+            'pymdownx.superfences',
+            'pymdownx.tabbed',
+            'pymdownx.tasklist',
+            'pymdownx.tilde',
+        ],
+        configkey='mdx_configs'
+    )
+    """PyMarkdown extension names."""
+
+    mdx_configs = c.Private[Dict[str, dict]]()
+    """PyMarkdown extension configs. Populated from `markdown_extensions`."""
+
+    strict = c.Type(bool, default=False)
+    """Enabling strict mode causes MkDocs to stop the build when a problem is
+    encountered rather than display an error."""
+
+    remote_branch = c.Type(str, default='gh-pages')
+    """The remote branch to commit to when using gh-deploy."""
+
+    remote_name = c.Type(str, default='origin')
+    """The remote name to push to when using gh-deploy."""
+
+    extra = c.SubConfig()
+    """extra is a mapping/dictionary of data that is passed to the template.
+    This allows template authors to require extra configuration that not
+    relevant to all themes and doesn't need to be explicitly supported by
+    MkDocs itself. A good example here would be including the current
+    project version."""
+
+    plugins = c.Plugins(theme_key='theme', default=['search', 'tags', 'privacy', 'minify', 'info', 'meta', 'blog'])
+    """A list of plugins. Each item may contain a string name or a key value pair.
+    A key value pair should be the string name (as the key) and a dict of config
+    options (as the value)."""
+
+    hooks = c.Hooks('plugins')
+    """A list of filenames that will be imported as Python modules and used as
+    an instance of a plugin each."""
+
+    watch = c.ListOfPaths(default=[])
+    """A list of extra paths to watch while running `mkdocs serve`."""
+
+    class Validation(base.Config):
+        class NavValidation(base.Config):
+            omitted_files = _LogLevel(default='info')
+            """Warning level for when a doc file is never mentioned in the navigation.
+            For granular configuration, see `not_in_nav`."""
+
+            not_found = _LogLevel(default='warn')
+            """Warning level for when the navigation links to a relative path that isn't an existing page on the site."""
+
+            absolute_links = _AbsoluteLinksValidation(default='info')
+            """Warning level for when the navigation links to an absolute path (starting with `/`)."""
+
+        nav = c.SubConfig(NavValidation)
+
+        class LinksValidation(base.Config):
+            not_found = _LogLevel(default='warn')
+            """Warning level for when a Markdown doc links to a relative path that isn't an existing document on the site."""
+
+            absolute_links = _AbsoluteLinksValidation(default='info')
+            """Warning level for when a Markdown doc links to an absolute path (starting with `/`)."""
+
+            unrecognized_links = _LogLevel(default='info')
+            """Warning level for when a Markdown doc links to a relative path that doesn't look like
+            it could be a valid internal link. For example, if the link ends with `/`."""
+
+            anchors = _LogLevel(default='info')
+            """Warning level for when a Markdown doc links to an anchor that's not present on the target page."""
+
+        links = c.SubConfig(LinksValidation)
+
+    validation = c.PropagatingSubConfig[Validation]()
+
+    _current_page: Page | None = None
+    """The currently rendered page. Please do not access this and instead
+    rely on the `page` argument to event handlers."""
+
+    def load_dict(self, patch: dict) -> None:
+        super().load_dict(patch)
+        if 'config_file_path' in patch:
+            raise base.ValidationError("Can't set config_file_path in config")
+
+    def load_file(self, config_file: IO) -> None:
+        """Load config options from the open file descriptor of a YAML file."""
+        loader = get_yaml_loader(config=self)
+        self.load_dict(yaml_load(config_file, loader))
+
+
+def get_schema() -> base.PlainConfigSchema:
+    """Soft-deprecated, do not use."""
+    return MkDocsConfig._schema