[tracker/sam/website: 52/56] Add an initial website for Tracker, built using mkdocs

[Sam Thursfield <sthursfield src gnome org>]

commit 89b7cb1a52a0edca6b488ef7b58a39830afbd1c5
Author: Sam Thursfield <sam afuera me uk>
Date:   Mon Dec 2 01:18:38 2019 +0100

    Add an initial website for Tracker, built using mkdocs
    
    Run `mkdocs` in the toplevel directory to generate the HTML.
    
    The last time Tracker had a website was 2011
    (http://web.archive.org/web/20110307070049/http://projects.gnome.org/tracker)
    so this is very exciting.

 docs/website/community.md     | 15 ++++++++
 docs/website/documentation.md | 32 ++++++++++++++++
 docs/website/faq.md           | 55 ++++++++++++++++++++++++++++
 docs/website/index.md         | 17 +++++++++
 docs/website/overview.md      | 85 +++++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml                    | 10 +++++
 6 files changed, 214 insertions(+)
---
diff --git a/docs/website/community.md b/docs/website/community.md
new file mode 100644
index 000000000..088e76f23
--- /dev/null
+++ b/docs/website/community.md
@@ -0,0 +1,15 @@
+# Community
+
+Tracker is community-driven Free Software, released under the [GNU GPL version 2 or 
later](https://spdx.org/licenses/GPL-2.0-or-later).
+
+Development happens at gitlab.gnome.org, in the
+[Tracker](https://gitlab.gnome.org/GNOME/tracker) and [Tracker 
Miners](https://gitlab.gnome.org/GNOME/tracker-miners) projects.
+You're invited to join in! See the [help wanted 
label](https://gitlab.gnome.org/GNOME/tracker/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=4.%20Help%20Wanted).
+
+Forum discussion takes place at
+[discourse.gnome.org](https://discourse.gnome.org/) -- please use the
+['tracker' tag](https://discourse.gnome.org/tags/tracker) for Tracker related
+posts.
+
+Real time discussion can be found in the #tracker channel on the GIMPnet IRC
+network.
diff --git a/docs/website/documentation.md b/docs/website/documentation.md
new file mode 100644
index 000000000..a156e9291
--- /dev/null
+++ b/docs/website/documentation.md
@@ -0,0 +1,32 @@
+# Documentation
+
+## User Documentation
+
+Tracker is a system component and most users will not need to interact with
+it directly.
+
+GNOME has documentation on how to
+[search for files in the file manager](https://developer.gnome.org/libtracker-sparql/stable/).
+
+The `tracker` commandline tool provides direct access to Tracker. Use the
+`--help` option for documentation of this tool.
+
+## Developer Documentation
+    
+Application and platform developers using Tracker will interact with Tracker
+using one or more of the shared libraries at provides:
+
+ * [libtracker-sparql](https://developer.gnome.org/libtracker-sparql/stable/) is
+   used to read and write data from the Tracker store using SPARQL.
+ * [libtracker-control](https://developer.gnome.org/libtracker-control/stable/),
+   is used to manage Tracker daemons.
+ * [libtracker-miner](https://developer.gnome.org/libtracker-miner/stable/) can
+   be used if you want to implement a new data provider while reusing existing
+   Tracker code.
+
+Developers are expected to read and write data from the Tracker store using the
+SPARQL.
+The following documentation may be useful:
+
+ * [Tracker ontology documentation](https://developer.gnome.org/ontology/stable/).
+ * [Tracker documentation on wiki.gnome.org](https://wiki.gnome.org/Projects/Tracker).
diff --git a/docs/website/faq.md b/docs/website/faq.md
new file mode 100644
index 000000000..8e3ae1ceb
--- /dev/null
+++ b/docs/website/faq.md
@@ -0,0 +1,55 @@
+# FAQ
+
+## Why is Tracker consuming lots of resources?
+
+Tracker automatically indexes content in your home directory.
+Tracker aims to perform well even on large collections of content, but there is
+a limit to how much it can index without causing noticably high CPU and IO
+usage.
+
+The problem may be:
+
+  * A very large amount of content being indexed by Tracker. See [How can I control what Tracker indexes?].
+  * A bug in Tracker or one of its dependencies
+
+## How can I control what Tracker indexes?
+
+In GNOME, you can use the Search Settings panel to control what Tracker
+indexes. See [GNOME's documentation](https://help.gnome.org/users/gnome-help/unstable/files-search.html.en).
+
+You can control Tracker's configuration directly using
+[dconf-editor](https://wiki.gnome.org/Apps/DconfEditor) or the `gsettings` CLI
+tool.
+The relevant schemas are `org.freedesktop.Tracker.Miner.Files` and
+`org.freedesktop.Tracker.Extract`.
+
+## How can I disable Tracker in GNOME?
+
+Tracker is a core dependency of GNOME, and some things will not work as
+expected if you disable it completely.
+
+If you are experiencing performance problems, you should first check that
+Tracker is only indexing data that you care about.
+
+In case you still see unwanted resource usage, you can tell Tracker not
+to index any directories on your system at all.
+This should bring resource usage close to zero. The Tracker daemons
+will still be started, but they should remain idle -- if they don't,
+this suggests there is a bug and we would appreciate if you report a bug.
+
+If the Tracker store is using a lot of disk space and you are sure that
+there is no unreplaceable data stored in the database, you can run `tracker
+reset --hard` to delete everything stored in the database.  
+
+## Can Tracker help me organize my music collection?
+
+At present, Tracker simply reads the metadata stores in your music files (often
+called 'tags').
+
+You may be able to use Gnome Music to correct this metadata using the
+Musicbrainz database.
+
+Programs that fix tags and organize music collections on disk, such as
+[Beets](http://beets.io/), work well with Tracker.
+
+[How can I control what Tracker indexes?]: #how-can-i-control-what-tracker-indexes
diff --git a/docs/website/index.md b/docs/website/index.md
new file mode 100644
index 000000000..92becdd03
--- /dev/null
+++ b/docs/website/index.md
@@ -0,0 +1,17 @@
+# Welcome to the Tracker project
+
+Tracker provides searching and indexing functionality for the
+[GNOME desktop environment](https://www.gnome.org/) and beyond.
+
+Are you having problems with Tracker in GNOME? Look at the [Frequently Asked
+Questions](faq).
+
+Are you interested in using or developing Tracker and want to find out more
+about it? Read the [overview](overview) first and then take a look at the
+[documentation](documentation).
+
+Do you want to contribute to Tracker? Join the [community](community)
+and look for some bugs marked 'Help wanted'
+([here](https://gitlab.gnome.org/GNOME/tracker/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=4.%20Help%20Wanted)
+and
+[here](https://gitlab.gnome.org/GNOME/tracker-miners/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=4.%20Help%20Wanted)).
diff --git a/docs/website/overview.md b/docs/website/overview.md
new file mode 100644
index 000000000..efcd1ed0d
--- /dev/null
+++ b/docs/website/overview.md
@@ -0,0 +1,85 @@
+# Overview
+
+## What is Tracker?
+
+Tracker is an efficient search engine and
+[triplestore](https://en.wikipedia.org/wiki/Triplestore) for desktop, embedded
+and mobile.
+
+It is a middleware component aimed at desktop application developers who
+want their apps to browse and search user content. It's not designed to be
+used directly by desktop users, but it provides a commandline tool named
+`tracker` for the adventurous.
+
+Tracker allows your application to instantly perform full-text searches across
+all documents. This feature is used by the 'search' bar in GNOME Files, for
+example.
+
+This is achieved by indexing the user's home directory in the background.
+
+Tracker also allows your application to query and list content that the user
+has stored. For example, GNOME Music displays all the music files that are
+found by Tracker. This means that GNOME Music doesn't need to maintain a
+database of its own.
+
+If you need to go beyond simple searches, you'll be happy to know that
+Tracker is also a [linked data](http://linkeddata.org/) endpoint and it
+understands [SPARQL](https://www.w3.org/TR/2013/REC-sparql11-overview-20130321/).
+
+Apps can also store their own data in the Tracker database, but this feature
+isn't widely used yet. The [next major version of
+Tracker](https://gitlab.gnome.org/GNOME/tracker/-/milestones/1) aims to bring
+improvements in this regard.
+
+There are several components that make up Tracker:
+
+  * **tracker-store**, which stores the index.
+  * **tracker-miner-fs**, a daemon which crawls and monitors the filesystem to find content
+  * **tracker-extract**, a suite of modules to extract metadata and content
+    from many different types of file.
+  * the **ontologies**, which define the database schema and the linked data vocabulary.
+
+## Who uses Tracker?
+
+### GNOME
+
+Tracker is a core dependency of the [GNOME desktop](https://www.gnome.org/).
+
+Gnome's [Shell](https://wiki.gnome.org/Projects/GnomeShell) doesn't use Tracker directly.
+Instead, the search results in the shell are provided by multiple apps on the system,
+using the [SearchProvider](https://developer.gnome.org/SearchProvider/) API.
+Some of these apps use Tracker internally, so they return search results
+provided by Tracker to gnome-shell.
+
+The following GNOME applications use Tracker:
+
+ * [GNOME Books](https://wiki.gnome.org/Apps/Books) (uses Tracker to find ebooks)
+ * [GNOME Boxes](https://wiki.gnome.org/Apps/Boxes) (uses Tracker to find VM images)
+ * [GNOME Documents](https://wiki.gnome.org/Apps/Documents) (uses Tracker to find documents)
+ * [GNOME Files](https://wiki.gnome.org/Apps/Files) (uses Tracker for full-text search within files)
+ * [GNOME Games](https://wiki.gnome.org/Apps/Games) (uses Tracker to find games)
+ * [GNOME Music](https://wiki.gnome.org/Apps/Music) (uses Tracker to find music and store playlist data)
+ * [GNOME Photos](https://wiki.gnome.org/Apps/Photos) (uses Tracker to find photos and store album data)
+ * [GNOME Videos](https://wiki.gnome.org/Apps/Videos) (uses Tracker to find video content)
+
+Although Tracker is able to store contacts and calendar entries,
+GNOME uses [Evolution Data Server](https://developer.gnome.org/platform-overview/stable/tech-eds.html)
+for this.
+
+### Sailfish OS
+
+[Sailfish OS](https://sailfishos.org) uses Tracker for [indexing media
+content](https://sailfishos.org/wiki/Core_Areas_and_APIs).
+
+## Related projects
+
+[Xapian](https://xapian.org/) provides similar functionality to Tracker.
+It focuses more on scalability and less on having a lightweight footprint.
+Unlike Tracker, it doesn't support SPARQL or provide a Linked Data endpoint.
+
+[Baloo](https://community.kde.org/Baloo) is a metadata and search framework by
+KDE, implemented using Xapian.
+
+[Apache Lucene + Solr](http://lucene.apache.org/) is a search engine which
+targets very large-scale workloads. It has a much heavier footprint compared to
+Tracker.
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 000000000..836ecf195
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,10 @@
+site_name: Tracker
+theme: cinder
+docs_dir: docs/website
+
+nav:
+  - Home: 'index.md'
+  - Overview: 'overview.md'
+  - FAQ: 'faq.md'
+  - Community: 'community.md'
+  - Documentation: 'documentation.md'