aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAdam Mathes <adam@trenchant.org>2018-07-04 16:54:55 -0700
committerAdam Mathes <adam@trenchant.org>2018-07-04 16:54:55 -0700
commitc97f927f3f1d6cc8333d41c92531dc5a32232144 (patch)
tree5f9ec2095125a53f3bfb92c02db25f5854728c23
parent893ea3825efea1f2ec187780e8653a1a2641d173 (diff)
downloadneko-c97f927f3f1d6cc8333d41c92531dc5a32232144.tar.gz
neko-c97f927f3f1d6cc8333d41c92531dc5a32232144.tar.bz2
neko-c97f927f3f1d6cc8333d41c92531dc5a32232144.zip
documentation updates
-rw-r--r--README.md138
-rw-r--r--readme.html248
2 files changed, 352 insertions, 34 deletions
diff --git a/README.md b/README.md
index 49d0be8..f20d94c 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,43 @@
+<pre style="font-family: menlo, courier, monospace;">
+ ▄▄
+ ██
+ ██▄████▄ ▄████▄ ██ ▄██▀ ▄████▄
+ ██▀ ██ ██▄▄▄▄██ ██▄██ ██▀ ▀██
+ ██ ██ ██▀▀▀▀▀▀ ██▀██▄ ██ ██
+ ██ ██ ▀██▄▄▄▄█ ██ ▀█▄ ▀██▄▄██▀
+ ▀▀ ▀▀ ▀▀▀▀▀ ▀▀ ▀▀▀ ▀▀▀▀
+
+
+
+ v0.2 manual
+ 7/4/2018
+</pre>
+<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-generate-toc again -->
+**Table of Contents**
+
+- [Neko](#neko)
+ - [Features](#features)
+ - [Screenshots](#screenshots)
+- [Installation](#installation)
+ - [Requirements](#requirements)
+ - [Building](#building)
+- [Configuration](#configuration)
+ - [Storage](#storage)
+- [Usage](#usage)
+ - [Web Interface](#web-interface)
+ - [Add Feed](#add-feed)
+ - [Crawl Feeds](#crawl-feeds)
+ - [Export](#export)
+- [All Command Line Options](#all-command-line-options)
+- [TODO](#todo)
+- [History](#history)
+ - [Early 2017](#early-2017)
+ - [July 2018 -- v0.2](#july-2018----v02)
+- [Feedback](#feedback)
+
+<!-- markdown-toc end -->
+
+
# Neko
`neko` is a self-hosted, rss reader focused on simplicity and efficiency.
@@ -14,21 +54,23 @@ Backend is written in `Go` and there is a simple javascript frontend and cat ear
* **k** - previous item
* that's all you should ever need
* automatically marks items read in an infinite stream of never-ending content (until you run out of content and it ends)
+ * full text search
+ * scrapes full text of pages on demand
## Screenshots
-![Alt text](/screenshot/neko.jpg?raw=true "Screenshot 1")
+![Screenshot 1](screenshot/neko.jpg?raw=true "Screenshot 1")
-![Alt text](/screenshot/neko2.jpg?raw=true "Screenshot 2")
+![Screenshot 2](screenshot/neko2.jpg?raw=true "Screenshot 2")
-## Installation
+# Installation
-### Requirements
+## Requirements
* [Go](https://golang.org)
* [SQLite](https://sqlite.org/)
-### Building
+## Building
$ go get adammathes.com/neko
@@ -36,11 +78,11 @@ This will download `neko`, dependencies, and build them all in `$GOPATH/src/`. B
A `neko` binary should now be in `$GOPATH/bin/`. By default this is usually `$HOME/go/bin/`
-## Configuration
+# Configuration
There's no configuration file -- everything is handled with a few command line flags. You shouldn't need to change the defaults most of the time.
-### Storage
+## Storage
By default `neko` will create the file `neko.db` in the current directory for storage.
@@ -48,11 +90,15 @@ You can override the location of this database file with the `--database` comman
$ neko --database=/var/db/neko.db --add=http://trenchant.org/rss.xml
-For expert users -- this is a [SQLite](https://sqlite.org/) database and can be manipulated with standard sqlite commands.
+For expert users -- this is a [SQLite](https://sqlite.org/) database and can be manipulated with standard sqlite commands --
+
+ $ sqlite3 neko.db .schema
+
+-- will print out the database schema.
-## Usage
+# Usage
-### Run Web Interface
+## Web Interface
You can do most of what you need to do with `neko` from the web interface, which is what `neko` does by default.
@@ -67,20 +113,22 @@ You can specify a different port using the `--http` option.
If you are hosting on a publicly available server instead of a personal computer, you can protect the interface with a password flag --
$ neko --password=rssisveryimportant
-
-### Add Feeds
+
+## Add Feed
You can add feeds directly from the command line for convenience --
$ neko --add=http://trenchant.org/rss.xml
-### Crawl Feeds
+## Crawl Feeds
+
+By default `neko` will crawl your feeds every 60 minutes while the interface is running, but if you want to manually crawl from the command line --
$ neko --update
This will fetch, download, parse, and store in the database your feeds.
-### Export
+## Export
Export de facto RSS feed standard OPML from the command line with --
@@ -92,17 +140,35 @@ Export is also available in the web interface.
Import of OPML and other things is a TODO item.
-## Operationalize
-
-### Crawl Regularly Via Cron
-
-Depending on your database file and other bits --
-
- 34 * * * * neko -d /home/neko/neko.db -u
-
--- should crawl regularly on the hour in cron.
-
-## TODO
+# All Command Line Options
+
+View all command line options with `-h` or `--help`
+
+ $ neko -h
+
+Usage of neko:
+ -a, --add http://example.com/rss.xml
+ add the feed at URL http://example.com/rss.xml
+ -d, --database string
+ sqlite database file (default "neko.db")
+ -x, --export string
+ export feed. format required: text, json or opml
+ -h, --help
+ print usage information
+ -s, --http int
+ HTTP port to serve on (default 4994)
+ -i, --imageproxy
+ rewrite and proxy all image requests for privacy (experimental)
+ -m, --minutes int
+ minutes between crawling feeds (default 60)
+ -p, --password string
+ password to access web interface
+ -u, --update
+ fetch feeds and store new items
+ -v, --verbose
+ verbose output
+
+# TODO
* manually initiate crawl/refresh from web interface
* auto-refresh feeds from web interface
@@ -112,21 +178,25 @@ Depending on your database file and other bits --
* prettify interface
* cross-compilation of binaries for "normal" platforms
-## History
+# History
-### Early 2017
+## Early 2017
I decided I didn't like the [original version of this that was python and mongo](https://github.com/adammathes/neko_v1) so rewrote it. I wanted to learn some Go. So assume the code is not great since I don't know what I'm doing even more so than normal.
The Javascript frontend is still the same, I keep saying I will rewrite that too since it's old backbone.js code but it still seems to mostly work. It's not very pretty though.
-### July 2018
+## July 2018 -- v0.2
Significant changes to simplify setup, configuration, usage. The goal was typing `neko` should be all you need to do to get started and use the software.
- * removed MySQL requirement (eliminating a ton of configuration and complexity)
- * added SQLite support (easier!)
- * auto-initialization of database file with embedded schema
- * removed json-formatted config file -- all options are command line options
- * `neko` runs web server by default
- * `neko` server crawls feeds regularly rather than requiring cron
+ * removed MySQL requirement (eliminating a ton of configuration and complexity)
+ * added SQLite support (easier!)
+ * auto-initialization of database file with embedded schema
+ * removed json-formatted config file -- all options are command line options
+ * `neko` runs web server by default
+ * `neko` server crawls feeds regularly rather than requiring cron
+
+# Feedback
+
+Pull requests and issues are welcomed at https://github.com/adammathes/neko
diff --git a/readme.html b/readme.html
new file mode 100644
index 0000000..573e5cc
--- /dev/null
+++ b/readme.html
@@ -0,0 +1,248 @@
+<pre style="font-family: menlo, courier, monospace;">
+ ▄▄
+ ██
+ ██▄████▄ ▄████▄ ██ ▄██▀ ▄████▄
+ ██▀ ██ ██▄▄▄▄██ ██▄██ ██▀ ▀██
+ ██ ██ ██▀▀▀▀▀▀ ██▀██▄ ██ ██
+ ██ ██ ▀██▄▄▄▄█ ██ ▀█▄ ▀██▄▄██▀
+ ▀▀ ▀▀ ▀▀▀▀▀ ▀▀ ▀▀▀ ▀▀▀▀
+
+
+
+ v0.2 manual
+ 7/4/2018
+</pre>
+
+
+<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-generate-toc again -->
+
+
+<p><strong>Table of Contents</strong></p>
+
+<ul>
+<li><a href="#neko">Neko</a>
+
+<ul>
+<li><a href="#features">Features</a></li>
+<li><a href="#screenshots">Screenshots</a></li>
+</ul>
+</li>
+<li><a href="#installation">Installation</a>
+
+<ul>
+<li><a href="#requirements">Requirements</a></li>
+<li><a href="#building">Building</a></li>
+</ul>
+</li>
+<li><a href="#configuration">Configuration</a>
+
+<ul>
+<li><a href="#storage">Storage</a></li>
+</ul>
+</li>
+<li><a href="#usage">Usage</a>
+
+<ul>
+<li><a href="#web-interface">Web Interface</a></li>
+<li><a href="#add-feed">Add Feed</a></li>
+<li><a href="#crawl-feeds">Crawl Feeds</a></li>
+<li><a href="#export">Export</a></li>
+</ul>
+</li>
+<li><a href="#all-command-line-options">All Command Line Options</a></li>
+<li><a href="#todo">TODO</a></li>
+<li><a href="#history">History</a>
+
+<ul>
+<li><a href="#early-2017">Early 2017</a></li>
+<li><a href="#july-2018----v02">July 2018 &ndash; v0.2</a></li>
+</ul>
+</li>
+<li><a href="#feedback">Feedback</a></li>
+</ul>
+
+
+<!-- markdown-toc end -->
+
+
+<h1>Neko</h1>
+
+<p><code>neko</code> is a self-hosted, rss reader focused on simplicity and efficiency.</p>
+
+<p>Backend is written in <code>Go</code> and there is a simple javascript frontend and cat ears.</p>
+
+<p><em>note: the cat ears are in your mind</em></p>
+
+<h2>Features</h2>
+
+<ul>
+<li> limited features (#1 feature)</li>
+<li> keyboard shortcuts
+
+<ul>
+<li><strong>j</strong> - next item</li>
+<li><strong>k</strong> - previous item</li>
+<li>that&rsquo;s all you should ever need</li>
+</ul>
+</li>
+<li> automatically marks items read in an infinite stream of never-ending content (until you run out of content and it ends)</li>
+</ul>
+
+
+<h2>Screenshots</h2>
+
+<p><img src="screenshot/neko.jpg?raw=true" title="Screenshot 1" alt="Screenshot 1" /></p>
+
+<p><img src="screenshot/neko2.jpg?raw=true" title="Screenshot 2" alt="Screenshot 2" /></p>
+
+<h1>Installation</h1>
+
+<h2>Requirements</h2>
+
+<ul>
+<li> <a href="https://golang.org">Go</a></li>
+<li> <a href="https://sqlite.org/">SQLite</a></li>
+</ul>
+
+
+<h2>Building</h2>
+
+<pre><code>$ go get adammathes.com/neko
+</code></pre>
+
+<p>This will download <code>neko</code>, dependencies, and build them all in <code>$GOPATH/src/</code>. By default this should be something like <code>$HOME/go/src/</code>.</p>
+
+<p>A <code>neko</code> binary should now be in <code>$GOPATH/bin/</code>. By default this is usually <code>$HOME/go/bin/</code></p>
+
+<h1>Configuration</h1>
+
+<p>There&rsquo;s no configuration file &ndash; everything is handled with a few command line flags. You shouldn&rsquo;t need to change the defaults most of the time.</p>
+
+<h2>Storage</h2>
+
+<p>By default <code>neko</code> will create the file <code>neko.db</code> in the current directory for storage.</p>
+
+<p>You can override the location of this database file with the <code>--database</code> command line option.</p>
+
+<pre><code>$ neko --database=/var/db/neko.db --add=http://trenchant.org/rss.xml
+</code></pre>
+
+<p>For expert users &ndash; this is a <a href="https://sqlite.org/">SQLite</a> database and can be manipulated with standard sqlite commands.</p>
+
+<h1>Usage</h1>
+
+<h2>Web Interface</h2>
+
+<p>You can do most of what you need to do with <code>neko</code> from the web interface, which is what <code>neko</code> does by default.</p>
+
+<pre><code>$ neko
+</code></pre>
+
+<p><code>neko</code> web interface should now be available at <code>127.0.0.1:4994</code> &ndash; opening a browser up to that should show you the interface.</p>
+
+<p>You can specify a different port using the <code>--http</code> option.</p>
+
+<pre><code>$ neko --http=9001
+</code></pre>
+
+<p>If you are hosting on a publicly available server instead of a personal computer, you can protect the interface with a password flag &ndash;</p>
+
+<pre><code>$ neko --password=rssisveryimportant
+</code></pre>
+
+<h2>Add Feed</h2>
+
+<p>You can add feeds directly from the command line for convenience &ndash;</p>
+
+<pre><code>$ neko --add=http://trenchant.org/rss.xml
+</code></pre>
+
+<h2>Crawl Feeds</h2>
+
+<p>By default <code>neko</code> will crawl your feeds every 60 minutes while the interface is running, but if you want to manually crawl from the command line &ndash;</p>
+
+<pre><code>$ neko --update
+</code></pre>
+
+<p>This will fetch, download, parse, and store in the database your feeds.</p>
+
+<h2>Export</h2>
+
+<p>Export de facto RSS feed standard OPML from the command line with &ndash;</p>
+
+<pre><code>$ neko --export=opml
+</code></pre>
+
+<p>Change <code>opml</code> to <code>text</code> for a simple list of feed URLs, or <code>json</code> for JSON formatted output.</p>
+
+<p>Export is also available in the web interface.</p>
+
+<p>Import of OPML and other things is a TODO item.</p>
+
+<h1>All Command Line Options</h1>
+
+<p>View all command line options with <code>-h</code> or <code>--help</code></p>
+
+<pre><code>$ neko -h
+</code></pre>
+
+<p>Usage of neko:
+ -a, &ndash;add http://example.com/rss.xml
+ add the feed at URL http://example.com/rss.xml
+ -d, &ndash;database string
+ sqlite database file (default &ldquo;neko.db&rdquo;)
+ -x, &ndash;export string
+ export feed. format required: text, json or opml
+ -h, &ndash;help
+ print usage information
+ -s, &ndash;http int
+ HTTP port to serve on (default 4994)
+ -i, &ndash;imageproxy
+ rewrite and proxy all image requests for privacy (experimental)
+ -m, &ndash;minutes int
+ minutes between crawling feeds (default 60)
+ -p, &ndash;password string
+ password to access web interface
+ -u, &ndash;update
+ fetch feeds and store new items
+ -v, &ndash;verbose
+ verbose output</p>
+
+<h1>TODO</h1>
+
+<ul>
+<li> manually initiate crawl/refresh from web interface</li>
+<li> auto-refresh feeds from web interface</li>
+<li> import</li>
+<li> mark all as read</li>
+<li> rewrite frontend in a modern js framework</li>
+<li> prettify interface</li>
+<li> cross-compilation of binaries for &ldquo;normal&rdquo; platforms</li>
+</ul>
+
+
+<h1>History</h1>
+
+<h2>Early 2017</h2>
+
+<p>I decided I didn&rsquo;t like the <a href="https://github.com/adammathes/neko_v1">original version of this that was python and mongo</a> so rewrote it. I wanted to learn some Go. So assume the code is not great since I don&rsquo;t know what I&rsquo;m doing even more so than normal.</p>
+
+<p>The Javascript frontend is still the same, I keep saying I will rewrite that too since it&rsquo;s old backbone.js code but it still seems to mostly work. It&rsquo;s not very pretty though.</p>
+
+<h2>July 2018 &ndash; v0.2</h2>
+
+<p>Significant changes to simplify setup, configuration, usage. The goal was typing <code>neko</code> should be all you need to do to get started and use the software.</p>
+
+<ul>
+<li> removed MySQL requirement (eliminating a ton of configuration and complexity)</li>
+<li> added SQLite support (easier!)</li>
+<li> auto-initialization of database file with embedded schema</li>
+<li> removed json-formatted config file &ndash; all options are command line options</li>
+<li> <code>neko</code> runs web server by default</li>
+<li> <code>neko</code> server crawls feeds regularly rather than requiring cron</li>
+</ul>
+
+
+<h1>Feedback</h1>
+
+<p>Pull requests and issues are welcomed at https://github.com/adammathes/snkt</p>