Merge pull request 'Convert from sphinx to mkdocs' (#1) from mkdocs into main

Reviewed-on: https://coastalcommits.com/SeaswimmerTheFsh/PyZipline/pulls/1

.gitignore

@@ -1 +1,2 @@
 __pycache__
+.cache

.readthedocs.yml

@@ -2,6 +2,14 @@
 
 build:
   os: "ubuntu-22.04"
+  apt_packages:
+    - libcairo2-dev
+    - libfreetype6-dev
+    - libffi-dev
+    - libjpeg-dev
+    - libpng-dev
+    - libz-dev
+    - pngquant
   tools:
     python: "3.12"
   jobs:
@@ -11,5 +19,5 @@ build:
     post_install:
       - poetry install --with docs
 
-sphinx:
-  configuration: docs/source/conf.py
+mkdocs:
+  configuration: mkdocs.yml

docs/Makefile

@@ -1,20 +0,0 @@
-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = source
-BUILDDIR      = build
-
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/css/external.css

@@ -0,0 +1,13 @@
+:root {
+  --external-link-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 512 512'%3E%3Clink xmlns='' type='text/css' rel='stylesheet' id='dark-mode-custom-link'/%3E%3Clink xmlns='' type='text/css' rel='stylesheet' id='dark-mode-general-link'/%3E%3Cstyle xmlns='' lang='en' type='text/css' id='dark-mode-custom-style'/%3E%3Cstyle xmlns='' lang='en' type='text/css' id='dark-mode-native-style'/%3E%3Cpath d='M432 320h-32a16 16 0 0 0-16 16v112H64V128h144a16 16 0 0 0 16-16V80a16 16 0 0 0-16-16H48a48 48 0 0 0-48 48v352a48 48 0 0 0 48 48h352a48 48 0 0 0 48-48V336a16 16 0 0 0-16-16zM488 0H360c-21.37 0-32.05 25.91-17 41l35.73 35.73L135 320.37a24 24 0 0 0 0 34L157.67 377a24 24 0 0 0 34 0l243.61-243.68L471 169c15 15 41 4.5 41-17V24a24 24 0 0 0-24-24z'/%3E%3C/svg%3E");
+}
+
+a[href^="http" ]:not(.md-button, [data-sub-html], .md-footer-social__link, .md-source, .md-search-result__link, .md-logo, .md-version__link, [href*="config.discordsrv.com"], [href*="squidfunk.github.io"], [href*="Documentation/edit"]):after {
+  background: transparent var(--external-link-icon) 0 0 no-repeat;
+  content: "";
+  display: inline-block;
+  height: 12px;
+  margin-left: 3px;
+  width: 12px;
+  filter: invert(1);
+}

docs/getting-started/installation.md

@@ -0,0 +1,31 @@
+# Installation
+
+/// admonition | This project is in active development.
+    type: danger
+There has not been an official release of PyZipline on PyPi yet, meaning these installation docs don't work.
+///
+
+## pip
+
+You can use pip to install PyZipline.  
+The command to use differs slightly depending on what OS/Distro you use.
+
+On Windows:
+
+``` prolog title="Command Prompt"
+py -m pip install -U pyzipline
+```
+
+On macOS and Linux:
+
+``` prolog title="Bash"
+python3 -m pip install pyzipline
+```
+
+## Poetry
+
+You can also use [Poetry](https://python-poetry.org/) to store your dependencies. Add PyZipline to your `pyproject.toml` file manually, or use this command:
+
+``` prolog title="Command Prompt / Shell"
+poetry add pyzipline
+```

docs/getting-started/usage.md

@@ -0,0 +1 @@
+# Usage

docs/index.md

@@ -0,0 +1,11 @@
+# Welcome to PyZipline
+
+/// admonition | This project is in active development.
+    type: warning
+These docs are not complete yet, and there is a lot still to do.
+///
+
+**PyZipline** is a Python API Wrapper for the [Zipline](https://zipline.diced.sh/) API.
+
+Check out the [usage](getting-started/usage.md) section for further information, including
+how to [install](getting-started/installation.md) the project.

docs/make.bat

@@ -1,35 +0,0 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=source
-set BUILDDIR=build
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd

docs/ref/zipline.md

@@ -0,0 +1,3 @@
+# API Reference
+
+::: pyzipline.zipline

docs/source/api.rst

@@ -1,19 +0,0 @@
-API Reference
-===
-
-.. autosummary::
-   :toctree: generated
-
-   pyzipline
-
-
-.. automodule:: zipline
-   :members:
-   :undoc-members:
-   :show-inheritance:
-   :inherited-members:
-   :noindex:
-   :exclude-members: __init__, __repr__, __str__
-
-   .. automethod:: zipline.function_name
-      :noindex:

docs/source/conf.py

@@ -1,36 +0,0 @@
-# pylint: skip-file
-# Configuration file for the Sphinx documentation builder.
-
-# -- Project information
-
-project = 'PyZipline'
-copyright = '2023, SeaswimmerTheFsh'
-author = 'SeaswimmerTheFsh'
-
-release = '3.7.7'
-version = '0.1.0'
-
-# -- General configuration
-
-extensions = [
-    'sphinx.ext.duration',
-    'sphinx.ext.doctest',
-    'sphinx.ext.autodoc',
-    'sphinx.ext.autosummary',
-    'sphinx.ext.intersphinx',
-]
-
-intersphinx_mapping = {
-    'python': ('https://docs.python.org/3/', None),
-    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
-}
-intersphinx_disabled_domains = ['std']
-
-templates_path = ['_templates']
-
-# -- Options for HTML output
-
-html_theme = 'sphinx_rtd_theme'
-
-# -- Options for EPUB output
-epub_show_urls = 'footnote'

docs/source/index.rst

@@ -1,20 +0,0 @@
-Welcome to PyZipline's documentation!
-===================================
-
-**PyZipline** is a Python API Wrapper for the Zipline API.
-
-Check out the :doc:`usage` section for further information, including
-how to :ref:`installation` the project.
-
-.. note::
-
-   This project is under active development.
-
-Contents
---------
-
-.. toctree::
-
-   usage
-   api
-   models

docs/source/models.rst

@@ -1,7 +0,0 @@
-API Reference
-===
-
-.. automodule:: pyzipline.models
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/usage.rst

@@ -1,13 +0,0 @@
-Usage
-=====
-
-.. _installation:
-
-Installation
-------------
-
-To use PyZipline, first install it using pip:
-
-.. code-block:: console
-
-   (.venv) $ pip install lumache

mkdocs.yml

@@ -0,0 +1,63 @@
+site_name: PyZipline Documentation
+site_url: https://pyzipline.readthedocs.io
+repo_name: CoastalCommits
+repo_url: https://coastalcommits.com/SeaswimmerTheFsh/PyZipline
+edit_uri: src/branch/main/docs
+copyright: Copyright © 2023, SeaswimmerTheFsh
+
+site_author: SeaswimmerTheFsh
+site_description: PyZipline is an API wrapper written in Python for the Zipline API.
+
+nav:
+  - Home: index.md
+  - Getting Started:
+    - Installation: getting-started/installation.md
+    - Usage: getting-started/usage.md
+  - Reference: ref/zipline.md
+
+plugins:
+  - git-revision-date-localized:
+      enable_creation_date: true
+  - search
+  - social
+  # - mkdocstrings:
+  #     default_handler: python
+  #     handlers:
+  #       python:
+  #         paths: [pyzipline]
+
+markdown_extensions:
+  - abbr
+  - attr_list
+  - pymdownx.blocks.details
+  - pymdownx.blocks.admonition
+  - pymdownx.saneheaders
+  - pymdownx.magiclink
+  - pymdownx.mark
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.emoji:
+      emoji_index: !!python/name:pymdownx.emoji.twemoji
+      emoji_generator: !!python/name:pymdownx.emoji.to_svg
+
+extra_css:
+  - css/external.css
+
+theme:
+  name: material
+  palette:
+    scheme: slate
+  features:
+    - content.code.copy
+    - content.tooltips
+    - navigation.instant
+    - search.suggest
+    - search.highlight
+    - search.share
+  logo: logo.png
+  favicon: logo.png

pyproject.toml

@@ -22,8 +22,10 @@ pylint = "^3.0.3"
 optional = true
 
 [tool.poetry.group.docs.dependencies]
-sphinx = "^7.2.6"
-sphinx-rtd-theme = "^2.0.0"
+mkdocs = "1.5.3"
+mkdocstrings = "0.24.0"
+mkdocs-git-revision-date-localized-plugin = "1.2.2"
+mkdocs-material = {extras = ["imaging"], version = "^9.5.2"}
 
 [build-system]
 requires = ["poetry-core"]

pyzipline/zipline.py

@@ -12,18 +12,16 @@ class ZiplineApi:
         enforced_signing: bool = True,
         logger: logging.Logger = None
     ):
-        """Constructor for ZiplineApi
+        """Constructor for ZiplineApi.
 
-        :param hostname: The hostname of your Zipline instance, WITHOUT https or http.
-        :type hostname: str
-        :param token: String used for authentication when making requests.
-        :type token: str, optional
-        :param ssl: Normally set to True, but if your Zipline instance doesn't use SSL/TLS, set this to False.
-        :type ssl: bool, optional
-        :param enforced_signing: Normally set to True, but if having SSL/TLS cert validation issues, can turn off with False.
-        :type enforced_signing: bool, optional
-        :param logger: If your app has a logger, pass it in here.
-        :type logger: logging.Logger, optional
+        All API requests should be made through this class.
+
+        Args:
+            hostname (str): The hostname of your Zipline instance, WITHOUT https or http.
+            token (str = None): String used for authentication when making requests.
+            ssl (bool = True): Normally set to True, but if your Zipline instance doesn't use SSL/TLS, set this to False.
+            enforced_signing (bool = True): Normally set to True, but if having SSL/TLS cert validation issues, can turn off with False.
+            logger (logging.Logger = None): If your app has a logger, pass it in here.
         """
         self._rest_adapter = RestAdapter(hostname=hostname, token=token, ssl=ssl, enforced_signing=enforced_signing, logger=logger)