add sphinx documentation setup

Author: pirate

Changelog.md

@@ -1,3 +1,5 @@
+# Changelog
+
 ▶️ *If you're having an issue with a breaking change, or migrating your data between versions, open an [issue](https://github.com/pirate/ArchiveBox/issues) to get help.*
 
 **`ArchiveBox` was previously named `Pocket Archive Stream` and then `Bookmark Archiver`.**
@@ -88,4 +90,4 @@ See the [releases](https://github.com/pirate/ArchiveBox/releases) page for versi
  - added Pocket-format export support
 
 ---
- - v0.0.0 released: created Pocket Archive Stream 2017/05/05
+ - v0.0.0 released: created Pocket Archive Stream 2017/05/05

Chromium-Install.md

@@ -1,3 +1,5 @@
+# Chromium Install
+
 By default, ArchiveBox looks for any existing installed version of Chrome/Chromium and uses it if found.  You can optionally install a specific version and set the environment variable `CHROME_BINARY` to force ArchiveBox to use that one, e.g.:  
 
  - `CHROME_BINARY=google-chrome-beta`
@@ -6,7 +8,7 @@ By default, ArchiveBox looks for any existing installed version of Chrome/Chromi
 
 If you don't already have Chrome installed, I recommend installing Chromium instead of Google Chrome, as it's the open-source fork of Chrome that doesn't send as much tracking data to Google.
 
-#### Check for existing Chrome/Chromium install
+**Check for existing Chrome/Chromium install:**
 
 <img src="https://i.imgur.com/FxFoIMH.jpg" width="25%" align="right"/> 
 
@@ -48,4 +50,4 @@ apt install google-chrome-beta
 
 ## Troubleshooting
 
-If you encounter problems setting up Google Chrome or Chromium, see the [Troubleshooting](https://github.com/pirate/ArchiveBox/wiki/Troubleshooting#chromiumgoogle-chrome) page.
+If you encounter problems setting up Google Chrome or Chromium, see the [Troubleshooting](https://github.com/pirate/ArchiveBox/wiki/Troubleshooting#chromiumgoogle-chrome) page.

Configuration.md

@@ -1,5 +1,6 @@
-▶️ *The default ArchiveBox config file can be found here: [`etc/ArchiveBox.conf.default`](https://github.com/pirate/ArchiveBox/blob/master/etc/ArchiveBox.conf.default).*
+# Configuration
 
+▶️ *The default ArchiveBox config file can be found here: [`etc/ArchiveBox.conf.default`](https://github.com/pirate/ArchiveBox/blob/master/etc/ArchiveBox.conf.default).*
 
 Configuration is done through environment variables.  You can pass in settings using all the usual environment variable methods: e.g. by using the `env` command, exporting variables in your shell profile, or sourcing a `.env` file before running the command.
 
@@ -384,31 +385,3 @@ Path or name of the curl binary to use.
 
 
 <img src="https://i.imgur.com/almAbwK.png" width="100%"/>
-
----
-
-
-# Creating a Config File
-
-*Note: If you're using Docker, see the [[Docker]] page for configuration instructions.*
-
-To set up a persistent config:
-
-1. Copy `etc/ArchiveBox.conf.default` to `~/.ArchiveBox.conf`
-```bash
-cp ArchiveBox/etc/ArchiveBox.conf.default ~/.ArchiveBox.conf
-```
-
-2. Edit your options inside `~/.ArchiveBox.conf`, e.g.:
-```bash
-CHROME_BINARY=google-chrome-stable
-RESOLUTION=1440,900
-FETCH_PDF=False
-```
-
-3. Source your config file when you run your archive script:
-```bash
-eval export $(grep -v '^#' ~/path/to/your/ArchiveBox.conf); ./archive https://example.com/rss/feed.xml
-```
-
-Improving this process is on the roadmap, in future versions you'll be able to pass a config file directly to the archive command.

Docker.md

@@ -1,4 +1,6 @@
-# Overview
+# Docker
+
+## Overview
 
 Running ArchiveBox with Docker allows you to manage it in a container without exposing it to the rest of your system.  Usage with Docker is similar to usage of ArchiveBox normally, with a few small differences.
 
@@ -30,7 +32,7 @@ echo 'https://example.com' | docker run -i -v ~/ArchiveBox:/data nikisweeting/ar
 
 <img src="https://i.imgur.com/knwOtky.png" height="40px" align="right">
 
-# Docker Compose
+## Docker Compose
 
 An example [`docker-compose.yml`](https://github.com/pirate/ArchiveBox/blob/master/docker-compose.yml) config with ArchiveBox and an Nginx server to serve the archive is included in the project root.  You can edit it as you see fit, or just run it as it comes out-of-the-box.
 
@@ -40,7 +42,7 @@ docker --version
 Docker version 18.09.1, build 4c52b90    # must be >= 17.04.0
 ```
 
-## Setup
+### Setup
 
 ```bash
 git clone https://github.com/pirate/ArchiveBox && cd ArchiveBox
@@ -50,7 +52,7 @@ docker-compose up -d
 
 Then open [`http://127.0.0.1:8098`](http://127.0.0.1:8098) or `data/index.html` to view the archive (HTTP, not HTTPS).
 
-## Usage
+### Usage
 
 First, make sure you're `cd`'ed into the same folder as your `docker-compose.yml` file (e.g. the project root) and that your containers have been started with `docker-compose up -d`.
 
@@ -73,13 +75,13 @@ docker-compose exec archivebox /bin/archive https://example.com/some/feed.rss
 ```
 Passing a URL as an argument here does not archive the specified URL, it downloads it and archives the links *inside* of it, so only use it for RSS feeds or other *lists of links* you want to add.  To add an individual link you want to archive use the instruction above and pass via stdin instead of by argument.
 
-## Accessing the data
+### Accessing the data
 
 The outputted archive data is stored in `data/` (relative to the project root), or whatever folder path you specified in the `docker-compose.yml` `volumes:` section.  Make sure the `data/` folder on the host has permissions initially  set to `777` so that the ArchiveBox command is able to set it to the specified `OUTPUT_PERMISSIONS` config setting on the first run.
 
 To access your archive, you can open `data/index.html` directly, or you can use the provided Nginx server running inside docker on [`http://127.0.0.1:8098`](http://127.0.0.1:8098).
 
-## Configuration
+### Configuration
 
 ArchiveBox running with docker-compose accepts all the same environment variables as normal, see the full list on the [[Configuration]] page.
 
@@ -107,9 +109,9 @@ If you want to access your archive server with HTTPS, put a reverse proxy like N
 
 ---
 
-# Docker
+## Docker
 
-## Setup
+### Setup
 
 Fetch and run the ArchiveBox Docker image to create your initial archive.
 ```bash
@@ -120,7 +122,7 @@ Replace `~/ArchiveBox` in the command above with the full path to a folder to us
 
 Make sure the data folder you use host is either a new, uncreated path, or if it already exists make sure it has permissions initially set to `777` so that the ArchiveBox command is able to set it to the specified `OUTPUT_PERMISSIONS` config setting on the first run.
 
-## Usage
+### Usage
 
 **To add a single URL to the archive** or a list of links from a file, pipe them in via stdin.  This will archive each link passed in.
 ```bash
@@ -135,17 +137,17 @@ docker run -v -v ~/ArchiveBox:/data nikisweeting/archivebox /bin/archive 'https:
 ```
 Passing a URL as an argument here does not archive the specified URL, it downloads it and archives the links *inside* of it, so only use it for RSS feeds or other *lists of links* you want to add.  To add an individual link use the instruction above and pass via stdin instead of by argument.
 
-## Accessing the data
+### Accessing the data
 
-### Using a bind folder
+#### Using a bind folder
 
 Use the flag:
 ```bash
 -v /full/path/to/folder/on/host:/data
 ```
 This will use the folder `/full/path/to/folder/on/host` on your host to store the ArchiveBox output.
 
-### Using a named Docker data volume 
+#### Using a named Docker data volume 
 
 ```bash
 docker volume create archivebox-data
@@ -164,7 +166,7 @@ screen ~/Library/Containers/com.docker.docker/Data/vms/0/tty
 cd /var/lib/docker/volumes/archivebox-data/_data
 ```
 
-## Configuration
+### Configuration
 
 ArchiveBox in Docker accepts all the same environment variables as normal, see the list on the [[Configuration]] page.
 
@@ -176,4 +178,4 @@ echo 'https://example.com' | docker run -i -v ~/ArchiveBox:/data nikisweeting/ar
 Or you can create an `ArchiveBox.env` file (copy from the default `etc/ArchiveBox.conf.default`) and pass it in like so:
 ```bash
 docker run -i -v --env-file=ArchiveBox.env nikisweeting/archivebox
-```
+```

Install.md

@@ -1,3 +1,5 @@
+# Install
+
 ArchiveBox only has a few main dependencies apart from `python3`, and they can all be installed using your normal package manager.  It usually takes 1min to get up and running if you use the [helper script](#automatic-setup), or about 5min if you install everything [manually](#manual-setup).
 
 <img src="https://lh4.googleusercontent.com/KWaqSJ_J9nSaGZugZWGR_mC18xxbGj2pVScriSzP8hX7KiUSw6L3VVL8rhDxQKIwxaCsfSFUO1B2pipEM4h7L-HJOGXo7yZK8a3DBVERwqfEZ8GxpeHPwh8P4LSkqVjPGRx5XYs" width="20%" align="right"/>
@@ -131,4 +133,4 @@ You may optionally specify a second argument to `archive.py export.html 15324242
 First, if you don't already have docker installed, follow the official install instructions for Linux, macOS, or Windows https://docs.docker.com/install/#supported-platforms.
 
 
-Then see the [[Docker]] page for next steps.
+Then see the [[Docker]] page for next steps.

Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+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)

Publishing-Your-Archive.md

@@ -1,4 +1,4 @@
-## Publishing Your Archive
+# Publishing Your Archive
 
 The archive produced by `./archive` is suitable for serving on any provider that can host static html (e.g. github pages!).
 
@@ -19,16 +19,15 @@ Make sure you're not running any content as CGI or PHP, you only want to serve s
 
 Urls look like: `https://archive.example.com/archive/1493350273/en.wikipedia.org/wiki/Dining_philosophers_problem.html`
 
-**Security WARNING & Content Disclaimer**
+## Security Concerns
 
-Re-hosting other people's content has security implications for any other sites sharing your hosting domain.  Make sure you understand
-the dangers of hosting unknown archived CSS & JS files [on your shared domain](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy).
-Due to the security risk of serving some malicious JS you archived by accident, it's best to put this on a domain or subdomain
-of its own to keep cookies separate and slightly mitigate [CSRF attacks](https://en.wikipedia.org/wiki/Cross-site_request_forgery) and other nastiness.
+Re-hosting other people's content has security implications for any other sites sharing your hosting domain.  Make sure you understand the dangers of hosting unknown archived CSS & JS files [on your shared domain](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy).
+Due to the security risk of serving some malicious JS you archived by accident, it's best to put this on a domain or subdomain of its own to keep cookies separate and slightly mitigate [CSRF attacks](https://en.wikipedia.org/wiki/Cross-site_request_forgery) and other nastiness.
 
-You may also want to blacklist your archive in `/robots.txt` if you don't want to be publicly assosciated with all the links you archive via search engine results.
+## Copyright Concerns
+
+Be aware that some sites you archive may not allow you to rehost their content publicly for copyright reasons, it's up to you to host responsibly and respond to takedown requests appropriately.
 
-Be aware that some sites you archive may not allow you to rehost their content publicly for copyright reasons,
-it's up to you to host responsibly and respond to takedown requests appropriately.
+You may also want to blacklist your archive in `/robots.txt` if you don't want to be publicly assosciated with all the links you archive via search engine results.
 
-Please modify the `FOOTER_INFO` config variable to add your contact info to the footer of your index.
+Please modify the `FOOTER_INFO` config variable to add your contact info to the footer of your index.

Quickstart.md

@@ -1,3 +1,5 @@
+# Quickstart
+
 <div align="center">
 <img src="https://i.imgur.com/ZbHpEf8.jpg" width="40%"/>
 </div>
@@ -72,4 +74,4 @@ Open `output/index.html` to view your archive.  (favicons will appear next to ea
  - Read [[Configuration]] to learn about the various archive method options
  - Read [[Scheduled Archiving]] to learn how to set up automatic daily archiving
  - Read [[Publishing Your Archive]] if you want to host your archive for others to access online
- - Read [[Troubleshooting]] if you encounter any problems
+ - Read [[Troubleshooting]] if you encounter any problems

README.md

@@ -0,0 +1 @@
+../README.md

Roadmap.md

@@ -1,4 +1,4 @@
-## Roadmap
+# Roadmap
 
 <img src="https://i.imgur.com/es97GGV.png" width="20%" align="right"/>
 
@@ -11,7 +11,7 @@ If you feel like contributing a PR, some of these tasks are pretty easy.  Feel f
 
 ---
 
-# Planned Specification
+## Planned Specification
 
 ArchiveBox is going to migrate towards this design spec over the next 3 months bit by bit as functionality gets implemented and refactors are released.
 
@@ -694,4 +694,4 @@ services:
 
 ---
 
-**IMPORTANT**: *Please don't work on any of these major long-term tasks without [contacting me first](https://nicksweeting.com/blog#Contact-Me), work is already in progress for many of these, and I may have to reject your PR if it doesn't align with the existing work!*
+**IMPORTANT**: *Please don't work on any of these major long-term tasks without [contacting me first](https://nicksweeting.com/blog#Contact-Me), work is already in progress for many of these, and I may have to reject your PR if it doesn't align with the existing work!*

Scheduled-Archiving.md

@@ -1,4 +1,6 @@
-## Schedule daily importing of new links into your archive
+# Scheduled Archiving
+
+## Using Cron
 
 To schedule regular archiving you can use any task scheduler like `cron`, `at`, `sytsemd`, etc.
 
@@ -8,7 +10,9 @@ ones as necessary.
 
 For some example configs, see the [`etc/cron.d`](https://github.com/pirate/ArchiveBox/blob/master/etc/cron.d) and [`etc/supervisord`](https://github.com/pirate/ArchiveBox/blob/master/etc/supervisord) folders.
 
-## Example: Import Firefox browser history every 24 hours
+## Examples
+
+### Example: Import Firefox browser history every 24 hours
 
 This example exports your browser history and archives it once a day:
 
@@ -26,7 +30,7 @@ cd /opt/ArchiveBox
 0 24 * * * www-data /opt/ArchiveBox/bin/firefox_custom.sh
 ```
 
-## Example: Import an RSS feed from Pocket every 12 hours
+### Example: Import an RSS feed from Pocket every 12 hours
 
 This example imports your Pocket bookmark feed and archives any new links once a day:
 
@@ -43,4 +47,4 @@ cd /opt/ArchiveBox
 **Then create a new file `/etc/cron.d/ArchiveBox-Pocket` to tell cron to run your script every 12 hours:**
 ```bash
 0 12 * * * www-data /opt/ArchiveBox/bin/pocket_custom.sh
-```
+```

Security-Overview.md

@@ -1,3 +1,5 @@
+# Security Overview
+
 ## Usage Modes
 
 ArchiveBox has three common usage modes outlined below.
@@ -64,4 +66,4 @@ How much are you planning to archive?  Only a few bookmarked articles, or thousa
 
 Are you publishing your archive? If so, make sure you're only serving it as HTML and not accidentally running it as php or cgi, and put it on its own domain not shared with other services.  This is done in order to avoid cookies leaking between your main domain and domains hosting content you don't control.  Many companies put user provided files on separate domains like googleusercontent.com and github.io to avoid this problem.
 
-Published archives automatically include a `robots.txt` `Dissallow: /` to block search engines from indexing them. You may still wish to publish your contact info in the index footer though using [`FOOTER_INFO`](https://github.com/pirate/ArchiveBox/wiki/Configuration#FOOTER_INFO) so that you can respond to any DMCA and copyright takedown notices if you accidentally rehost copyrighted content.
+Published archives automatically include a `robots.txt` `Dissallow: /` to block search engines from indexing them. You may still wish to publish your contact info in the index footer though using [`FOOTER_INFO`](https://github.com/pirate/ArchiveBox/wiki/Configuration#FOOTER_INFO) so that you can respond to any DMCA and copyright takedown notices if you accidentally rehost copyrighted content.