migrate from sphinx to mkdocs

fastily · Dec 1, 2023 · 7ad365d · 7ad365d
1 parent 3236e8c
commit 7ad365d
Show file tree

Hide file tree

Showing 20 changed files with 105 additions and 282 deletions.
diff --git 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
@@ -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/)
diff --git a/build_docs.sh b/build_docs.sh
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/dwrap-reference.md b/docs/dwrap-reference.md
@@ -0,0 +1,2 @@
+# dwrap
+::: pwiki.dwrap
diff --git a/docs/examples.md 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!")
+```
diff --git a/docs/gquery-reference.md b/docs/gquery-reference.md
@@ -0,0 +1,2 @@
+# gquery
+::: pwiki.gquery
diff --git a/docs/index.md 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
+```
diff --git a/docs/make.bat b/docs/make.bat
diff --git a/docs/mquery-reference.md b/docs/mquery-reference.md
@@ -0,0 +1,2 @@
+# mquery
+::: pwiki.mquery
diff --git a/docs/ns-reference.md b/docs/ns-reference.md
@@ -0,0 +1,2 @@
+# ns
+::: pwiki.ns
diff --git a/docs/oquery-reference.md b/docs/oquery-reference.md
@@ -0,0 +1,2 @@
+# oquery
+::: pwiki.oquery
diff --git a/docs/source/conf.py b/docs/source/conf.py
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
diff --git a/docs/source/reference.rst b/docs/source/reference.rst
diff --git a/docs/wiki-reference.md 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
@@ -0,0 +1,2 @@
+# wparser
+::: pwiki.wparser