From 7ad365db63cb60708f13d90b1810fc4cd74bb21d Mon Sep 17 00:00:00 2001 From: fastily Date: Fri, 1 Dec 2023 00:39:18 -0800 Subject: [PATCH] migrate from sphinx to mkdocs --- .gitignore | 3 ++ README.md | 9 +++++ build_docs.sh | 3 -- docs/Makefile | 20 ---------- docs/dwrap-reference.md | 2 + docs/examples.md | 42 +++++++++++++++++++++ docs/gquery-reference.md | 2 + docs/index.md | 11 ++++++ docs/make.bat | 35 ----------------- docs/mquery-reference.md | 2 + docs/ns-reference.md | 2 + docs/oquery-reference.md | 2 + docs/source/conf.py | 68 ---------------------------------- docs/source/examples.rst | 55 --------------------------- docs/source/index.rst | 36 ------------------ docs/source/reference.rst | 64 -------------------------------- docs/wiki-reference.md | 2 + docs/wparser-reference copy.md | 2 + mkdocs.yml | 23 ++++++++++++ requirements-docs.txt | 4 +- 20 files changed, 105 insertions(+), 282 deletions(-) delete mode 100644 build_docs.sh delete mode 100644 docs/Makefile create mode 100644 docs/dwrap-reference.md create mode 100644 docs/examples.md create mode 100644 docs/gquery-reference.md create mode 100644 docs/index.md delete mode 100644 docs/make.bat create mode 100644 docs/mquery-reference.md create mode 100644 docs/ns-reference.md create mode 100644 docs/oquery-reference.md delete mode 100644 docs/source/conf.py delete mode 100644 docs/source/examples.rst delete mode 100644 docs/source/index.rst delete mode 100644 docs/source/reference.rst create mode 100644 docs/wiki-reference.md create mode 100644 docs/wparser-reference copy.md create mode 100644 mkdocs.yml diff --git a/.gitignore b/.gitignore index e9165a3..9678b37 100644 --- a/.gitignore +++ b/.gitignore @@ -16,6 +16,9 @@ build dist *.egg-info +# Docs +site/ + # virtualenv venv_pwiki diff --git a/README.md b/README.md index 9614b35..a85b3ce 100644 --- a/README.md +++ b/README.md @@ -11,5 +11,14 @@ pwiki is a Python library for effortlessly interacting with Wikipedia/MediaWiki pip install pwiki ``` +## Build docs +```bash +# make sure doc requirements are installed +pip install -r requirements-docs.txt + +# build docs +mkdocs build +``` + ## Resources * [API Docs](https://fastily.github.io/pwiki/) \ No newline at end of file diff --git a/build_docs.sh b/build_docs.sh deleted file mode 100644 index 145dbf0..0000000 --- a/build_docs.sh +++ /dev/null @@ -1,3 +0,0 @@ -#!/usr/bin/env bash - -sphinx-build -b html docs/source/ docs/build/html \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf..0000000 --- a/docs/Makefile +++ /dev/null @@ -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) diff --git a/docs/dwrap-reference.md b/docs/dwrap-reference.md new file mode 100644 index 0000000..f4213a7 --- /dev/null +++ b/docs/dwrap-reference.md @@ -0,0 +1,2 @@ +# dwrap +::: pwiki.dwrap diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000..b14becb --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,42 @@ +# Examples +⚠️ This section is under construction + +## Basics +```python +from pwiki.wiki import Wiki + +# new Wiki instance, pointed to en.wikipedia.org, not logged in +wiki = Wiki() + +# new Wiki instance, pointed at commons.wikimedia.org, logging in with user/pass +wiki = Wiki("commons.wikimedia.org", "MyCoolUsername", "MySuperSecretPassword") +``` + +## Read Page Content +```python +from pwiki.wiki import Wiki + +wiki = Wiki() + +# print all the titles in "Category:American 3D films" +for title in wiki.category_members("Category:American 3D films"): + print(title) + +# print all external links on the page "GitHub" +for url in wiki.external_links("GitHub"): + print(url) +``` + +## Edit/Create Page Content +```python +from pwiki.wiki import Wiki + +# you'll need to create a real account on Wikipedia otherwise the snippets below won't work +wiki = Wiki(username="MyCoolUsername", password="MySuperSecretPassword") + +# Append "this is a test" to "Wikipedia:Sandbox" +wiki.edit("Wikipedia:Sandbox", append="this is a test") + +# Replace "Wikipedia:Sandbox" with "I changed the page!" and edit summary "Hello, world!" +wiki.edit("Wikipedia:Sandbox", "I changed the page!", "Hello, world!") +``` \ No newline at end of file diff --git a/docs/gquery-reference.md b/docs/gquery-reference.md new file mode 100644 index 0000000..b90fb8a --- /dev/null +++ b/docs/gquery-reference.md @@ -0,0 +1,2 @@ +# gquery +::: pwiki.gquery diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..9a21c9a --- /dev/null +++ b/docs/index.md @@ -0,0 +1,11 @@ +# Welcome to pwiki's docs + +**pwiki** is a Python library which makes interacting with the MediaWiki API simple and easy. It can be used with sites such as Wikipedia, or virtually any other website that runs on MediaWiki. + +## Installation + +Install with `pip` + +```bash +pip install pwiki +``` \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 6fcf05b..0000000 --- a/docs/make.bat +++ /dev/null @@ -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.https://www.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 diff --git a/docs/mquery-reference.md b/docs/mquery-reference.md new file mode 100644 index 0000000..b393c59 --- /dev/null +++ b/docs/mquery-reference.md @@ -0,0 +1,2 @@ +# mquery +::: pwiki.mquery diff --git a/docs/ns-reference.md b/docs/ns-reference.md new file mode 100644 index 0000000..059d8ee --- /dev/null +++ b/docs/ns-reference.md @@ -0,0 +1,2 @@ +# ns +::: pwiki.ns diff --git a/docs/oquery-reference.md b/docs/oquery-reference.md new file mode 100644 index 0000000..a92761e --- /dev/null +++ b/docs/oquery-reference.md @@ -0,0 +1,2 @@ +# oquery +::: pwiki.oquery diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index f561dae..0000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,68 +0,0 @@ -"""pwiki sphinx doc config. To build docs run `sphinx-build -b html docs/source/ docs/build/html` from project root directory""" - -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - -import sys - -from datetime import datetime -from pathlib import Path - -sys.path.insert(0, Path(__file__).parents[2].resolve().as_posix()) - -# -- Project information ----------------------------------------------------- - -project = 'pwiki' -author = 'Fastily' -copyright = f'{datetime.today().year}, {author}' - -# The full version, including alpha/beta/rc tags -release = '1.1.1' - - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'sphinx.ext.autodoc', - # 'sphinx.ext.autosummary', - 'sphinx.ext.napoleon' -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'bizstyle' - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -autodoc_preserve_defaults = True # don't interpret defualt function parameters diff --git a/docs/source/examples.rst b/docs/source/examples.rst deleted file mode 100644 index 65b21f2..0000000 --- a/docs/source/examples.rst +++ /dev/null @@ -1,55 +0,0 @@ -Examples -======== - -.. note:: - - This section is under construction - - -Basics ------- - -.. code-block:: python - - from pwiki.wiki import Wiki - - # new Wiki instance, pointed to en.wikipedia.org, not logged in - wiki = Wiki() - - # new Wiki instance, pointed at commons.wikimedia.org, logging in with user/pass - wiki = Wiki("commons.wikimedia.org", "MyCoolUsername", "MySuperSecretPassword") - - -Read Page Content ------------------ - -.. code-block:: python - - from pwiki.wiki import Wiki - - wiki = Wiki() - - # print all the titles in "Category:American 3D films" - for title in wiki.category_members("Category:American 3D films"): - print(title) - - # print all external links on the page "GitHub" - for url in wiki.external_links("GitHub"): - print(url) - - -Edit/Create Page Content -------------------------- - -.. code-block:: python - - from pwiki.wiki import Wiki - - # you'll need to create a real account on Wikipedia otherwise the snippets below won't work - wiki = Wiki(username="MyCoolUsername", password="MySuperSecretPassword") - - # Append "this is a test" to "Wikipedia:Sandbox" - wiki.edit("Wikipedia:Sandbox", append="this is a test") - - # Replace "Wikipedia:Sandbox" with "I changed the page!" and edit summary "Hello, world!" - wiki.edit("Wikipedia:Sandbox", "I changed the page!", "Hello, world!") diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index d4075cf..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. pwiki documentation master file, created by - sphinx-quickstart on Tue Jan 18 16:14:36 2022. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to pwiki's documentation! -================================= - -**pwiki** is a Python library which makes interacting with the MediaWiki API simple and easy. It can be used with sites such as Wikipedia, or virtually any other website that runs on MediaWiki. - - -Installation ------------- - -Install with pip: - -.. code-block:: bash - - pip install pwiki - - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - examples - reference - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/source/reference.rst b/docs/source/reference.rst deleted file mode 100644 index 4342377..0000000 --- a/docs/source/reference.rst +++ /dev/null @@ -1,64 +0,0 @@ -API reference -============= - -pwiki.dwrap ------------------- - -.. automodule:: pwiki.dwrap - :members: - :undoc-members: - :show-inheritance: - - -pwiki.gquery -------------------- - -.. automodule:: pwiki.gquery - :members: - :undoc-members: - :show-inheritance: - - -pwiki.mquery -------------------- - -.. automodule:: pwiki.mquery - :members: - :undoc-members: - :show-inheritance: - - -pwiki.ns ---------------- - -.. automodule:: pwiki.ns - :members: - :undoc-members: - :show-inheritance: - - -pwiki.oquery ---------------- - -.. automodule:: pwiki.oquery - :members: - :undoc-members: - :show-inheritance: - - -pwiki.wiki ------------------ - -.. automodule:: pwiki.wiki - :members: - :undoc-members: - :show-inheritance: - - -pwiki.wparser --------------------- - -.. automodule:: pwiki.wparser - :members: - :undoc-members: - :show-inheritance: diff --git a/docs/wiki-reference.md b/docs/wiki-reference.md new file mode 100644 index 0000000..93faf25 --- /dev/null +++ b/docs/wiki-reference.md @@ -0,0 +1,2 @@ +# wiki +::: pwiki.wiki diff --git a/docs/wparser-reference copy.md b/docs/wparser-reference copy.md new file mode 100644 index 0000000..775e6c2 --- /dev/null +++ b/docs/wparser-reference copy.md @@ -0,0 +1,2 @@ +# wparser +::: pwiki.wparser diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..ebf1d4a --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,23 @@ +site_name: pwiki docs +site_url: https://example.com/ + +theme: + name: material + palette: + scheme: slate + +plugins: + - mkdocstrings: + handlers: + python: + options: + show_source: false + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences \ No newline at end of file diff --git a/requirements-docs.txt b/requirements-docs.txt index f3f572c..199bd4f 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1 +1,3 @@ -Sphinx==4.4.0 \ No newline at end of file +mkdocs +mkdocs-material +mkdocstrings[python] \ No newline at end of file