expand docs, tweak structure

fastily · Apr 22, 2024 · c8e3515 · c8e3515
1 parent ba0f0c8
commit c8e3515
Show file tree

Hide file tree

Showing 10 changed files with 46 additions and 14 deletions.
diff --git a/docs/dwrap-reference.md → docs/API/dwrap-reference.md b/docs/dwrap-reference.md → docs/API/dwrap-reference.md
diff --git a/docs/gquery-reference.md → docs/API/gquery-reference.md b/docs/gquery-reference.md → docs/API/gquery-reference.md
diff --git a/docs/mquery-reference.md → docs/API/mquery-reference.md b/docs/mquery-reference.md → docs/API/mquery-reference.md
diff --git a/docs/ns-reference.md → docs/API/ns-reference.md b/docs/ns-reference.md → docs/API/ns-reference.md
diff --git a/docs/oquery-reference.md → docs/API/oquery-reference.md b/docs/oquery-reference.md → docs/API/oquery-reference.md
diff --git a/docs/wiki-reference.md → docs/API/wiki-reference.md b/docs/wiki-reference.md → docs/API/wiki-reference.md
diff --git a/docs/wparser-reference copy.md → docs/API/wparser-reference.md b/docs/wparser-reference copy.md → docs/API/wparser-reference.md
diff --git a/docs/examples.md b/docs/examples.md
@@ -1,5 +1,5 @@
 # Examples
-⚠️ This section is under construction
+This is a non-exhaustive collection of snippets exhibiting some of the functionality `pwiki` is capable of.
 
 ## Basics
 ```python
@@ -10,6 +10,12 @@ wiki = Wiki()
 
 # new Wiki instance, pointed at commons.wikimedia.org, logging in with user/pass
 wiki = Wiki("commons.wikimedia.org", "MyCoolUsername", "MySuperSecretPassword")
+
+# login on en.wikipedia.org as MyCoolUsername.  Password will be read from environment variable "MyCoolUsername_PW"
+wiki = Wiki(username="MyCoolUsername")
+
+# save cookies so they can automatically be reused for next time
+wiki.save_cookies()
 ```
 
 ## Read Page Content
@@ -18,16 +24,14 @@ 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)
+# get all the titles in "Category:American 3D films"
+print(wiki.category_members("Category:American 3D films"))
 
-# print all external links on the page "GitHub"
-for url in wiki.external_links("GitHub"):
-    print(url)
+# get all external links on the page "GitHub"
+print(wiki.external_links("GitHub")):
 ```
 
-## Edit/Create Page Content
+## Edit/Create Content
 ```python
 from pwiki.wiki import Wiki
 
@@ -39,4 +43,22 @@ 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!")
+
+# Upload a file
+from pathlib import Path
+wiki.upload(Path("/path/to/file.jpg"), "My awesome new file on Wikipedia.jpg", "my file description", "test edit summary")
+```
+
+## Categories
+```python
+from pwiki.ns import NS
+from pwiki.wiki import Wiki
+
+wiki = Wiki()
+
+# get all category members of "Category:Some Cool Category"
+print(wiki.category_members("Category:Some Cool Category"))
+
+# get all category members of "Category:Some Cool Category" in the File namespace
+print(wiki.category_members("Category:Some Cool Category", NS.FILE))
 ```
diff --git a/docs/index.md b/docs/index.md
@@ -1,11 +1,21 @@
-# Welcome to pwiki's docs
+# Introduction
+[![Python 3.9+](https://upload.wikimedia.org/wikipedia/commons/4/4f/Blue_Python_3.9%2B_Shield_Badge.svg)](https://www.python.org)
+[![MediaWiki 1.35+](https://upload.wikimedia.org/wikipedia/commons/b/b3/Blue_MediaWiki_1.35%2B_Shield_Badge.svg)](https://www.mediawiki.org/wiki/MediaWiki)
+[![License: GPL v3](https://upload.wikimedia.org/wikipedia/commons/8/86/GPL_v3_Blue_Badge.svg)](https://www.gnu.org/licenses/gpl-3.0.en.html)
 
 **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
-```
+```
+
+## Overview
+I created `pwiki` with the goal of being simple and powerful, all while being mindful of DX (developer experience).  This means that every interaction with the API is simple, easy, and usually just one line of code.
+
+`pwiki` is split into four main modules:
+
+1. [wiki](API/wiki-reference.md) - The main API and entry point.  This module ecompasses most of the functionality for reading from/writing to MediaWiki.
+2. [mquery](API/mquery-reference.md) - The batch query API.  This module makes it easy to efficiently query against many titles/articles on the MediaWiki instance in fewer round-trips.
+3. [gquery](API/gquery-reference.md) - A batch query API that uses python generators to efficiently query for results.  This is useful for sampling large quantities of data from MediaWiki in a piecemeal fashion.
+4. [wparser](API/wparser-reference.md) - Contains methods for parsing wikitext into higher level object-based models that are easy to work with.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -1,4 +1,4 @@
-site_name: pwiki docs
+site_name: pwiki documentation
 site_url: https://fastily.github.io/pwiki/
 
 theme: