@ -27,11 +27,21 @@ Develop tools to facilitate rich software documentation. To assist and stimulate
### How do you plan to make it?
Define a domain of research. Where does software documentation begin and where does it end? What about tutorials, guidelines, and demos? How porous or tentacular is this surface?
Define a domain of research. Where does software documentation begin and where does it end? What about tutorials, guidelines, and demos? How porous or tentacular is this surface? Set some references by looking back at the works made last year and read them through the axis of code and care.
Set some references by looking back at the works made last year and read them through the axis of code and care. Or some other system of coordinates that suits better. Could the process of writing documentation reactivate old prototypes, or cast different light onto them?
Start writing documentation for selected prototypes from the many made last year: could this process create a new public, or transform their original ones?
Expand the research to tap into ongoing projects outside XPUB, such as freelance works and [parallel research](../ooc-summer-session/). Are there ways to make the documentation process more sustainable? Are there strategies to overcome a low-resources environment? What are the relations between documentation and the communities around a software?
As initial case study focus on the Padliography, a tool developed within XPUB to keep track of the amount of scattered Etherpad documents used to take notes and work togheter. During last year it's been used only in the context of our class, but after some adjustments it's now flexible enough to be offered also to other constellations orbiting around the _XPUB & Lens-Based wiki_.
Open the writing process to include collaborative practices for the documentation of the Workbook. This is a joint project started with Supi to build an online-modular-workbook-cms to learn how analog synths work through interactive annotation.
Write the documentation together. Could there be multiple voices or is necessary to keep a single point of view? Experiment with versioning. Try to have several instances of the same documentation.
Expand the research to tap into ongoing projects outside XPUB, such as freelance works and parallel research such as [OOC](../ooc-summer-session/).
Are there ways to make the documentation process more sustainable (socially, economically)? Are there strategies to overcome a low-resources environment? Search for escamotages to create space and energies to document. Work with collaborators, clients, and end-users to approach code from multiple point of view.
What are the relations between documentation and the community around a software?
The Padliography is a tool to keep track of our pads. It is built to interact with the MediaWiki API, and it uses [XPUB & Lens-Based Wiki](https://pzwiki.wdka.nl/mediadesign/Main_Page)'s pages as archive.
A way to create, archive and retrieve our pads. Now with a fast way to insert new pads without too much effort uiii.
# Features
**Features:**
- Multiple archives
- Custom categories
- Filter by categories
- Table sorting
- Create new pad if URL is not provided
- Table Sorting
- Create new pad
- Interact with the wiki
## Quick Start
The Padliography homepage loads by default the XPUB2 archive. Just above the pads list it is indicated from where the pads are being fetched, and it is possible to change source by inserting the title of the page in which the other archive is.
To create a brand new archive click on `Init a new padliography` and insert a title and a short description to put in the wiki.
**Watch out:** This action will create a new blank page, so check that there is not already something with the same title in the wiki, or it will be overwritten. Thanks to the wiki's history, it is possible to recover overwritten contents, so the contents are not in total danger.
Use the **Add new pad** form to insert a pad in the archive. The required information are a title, the URL of the document, a short description, a date and some categories. The categories are custom, and are useful to organize pads in themes or context.
The **Filter Categories** section loads all the categories from the current archive and uses it to filter the list of pads.
The list of pads is sortable. Click on the headers to order the pad, click twice to invert the order.
At the moment this Padliography instance runs on the [Soupboat](https://hub.xpub.nl/soupboat/). If you are using it a lot or with a lot of pads, consider to install a new instance on a different environment, in order not to put a strain on the small Raspberry. It should be fine anyway.
## How does it work
To have an overview over the lifecycle of the Padliography let's start from the wiki.
The pads are stored in a page with a minimal template, such as the title, a short description and a section named Padliography with the archive. Here they are organized in a table that has the CSS class `padliography`.
Through the [MediaWiki API](https://pzwiki.wdka.nl/mediadesign/Special:ApiSandbox) we can request the contents of this page from somewhere else. This somewhere else is a small Raspberry Pi called Soupboat and installed on the 4th floor of the WdKA.
The Soupboat is a small server, and it runs a [Flask](https://flask.palletsprojects.com/en/2.2.x/) application that interacts with the wiki using the [mwclient](https://mwclient.readthedocs.io/en/latest/index.html) python library.
When a user enters the homepage of the padliography, the Flask application returns a [Vue3](https://vuejs.org/) app and through that requests to the wiki API the list of pads.
The response from the MediaWiki API is parsed on the server using [BeautifulSoup](https://www.crummy.com/software/BeautifulSoup/), that tries to find the `padliography` table with some CSS selectors and then builds a list of pads organized by the properties of the table's headers. The list of table is sent to the Vue app as JSON message, and used to compile a fancy sortable table and filtering system.
When a user interacts with the form to add a new pad the process is the same, but in the opposite direction: first the Vue app sends the data to the Flask application that in turns tries to add it in the archive wiki page.
## Development
### Local setup
To install the Padliography somewhere else start by cloning this repo.
```
git clone https://git.xpub.nl/kamo/pad-bis.git
```
Then move to the cloned repository folder and create a python virtual environment.
```
cd pad-bis
python3 -m venv venv
```
Activate the virtual environment
```
# on unix
source venv/bin/activate
# on windows
venv\Scripts\activate
```
and then install the requirements with pip. The **.** here refers to the current working directory, where the **setup.py** file can be found. There are specified all the packages the application needs.
```
pip install -e .
```
Once the installation is completed, launch the application and open it on the default port .
```
python pad-bis.py
```
If you open `localhost:5000` on your browser, it will return the padliography stuck in the loading process. This is why before interacting with the MediaWiki API we need to specify the credential for a user to log into the wiki. On your local version you can use your own credentials, but if you plan to put this padliography online it's better to use a dedicated user, aka a bot.
Remember not to commit your credentials on git, or they will be rendered public! Instead create and `.env` file, that will not be uploaded on git as specified in the `.gitignore` file.
Create an `.env` file in your working directory with the following properties:
```
MW_BOT= your username
MW_KEY= your password
```
At this step you are up and running, the padliography should be able to fetch the pad from the wiki etc.
<!-- TODO: put the padliography online -->
# TODO
<!-- ### Online configuration
- Setup script
- Search
- Server side rendering?
Going online depends on several variables, many of them being out of reach.
For this reason this section doesn't provide a comprehensive guide to put the project online, but just a reference to the configuration currently in use on the Soupboat.
This Padliography was distilled with the help and within the context of XPUB, 2022.
Copyleft with a difference: This is a collective work, you are invited to copy, distribute, and modify it under the terms of the [CC4r](https://constantvzw.org/wefts/cc4r.en.html).
