Commits

David Larlet  committed f328f2e

Add documentation at the /doc URL

  • Participants
  • Parent commits 07c86fe

Comments (0)

Files changed (12)

 
 Go to the running URL and enjoy a clutter free browsing experience!
 
-*Bonus: web pages are archived in redis, thanks to whoosh you can even search in your history :)*
+Read the whole documentation at `/doc` directly in your new browser.
 
 ## Hacking
 

File src/browser.py

             Rule('/', endpoint='new_url'),
             Rule('/r', endpoint='render_content'),
             Rule('/s', endpoint='search_content'),
+            Rule('/doc', endpoint='documentation'),
         ])
 
     def on_new_url(self, request):
                 theme=CSS_THEME
             )
 
+    def on_documentation(self, request):
+        """View that displays documentation."""
+        return self.render_template('documentation.html',
+            theme=CSS_THEME
+        )
+
     ## WERKZEUG INTERNALS (see http://werkzeug.pocoo.org/docs/tutorial/)
 
     def render_template(self, template_name, **context):

File src/settings.py

 WHOOSH_INDEX = 'index'
 
 # Werkzeug's settings
-USE_DEBUGGER = True
-USE_RELOADER = True
+USE_DEBUGGER = False
+USE_RELOADER = False
 
 # You shouldn't have to customize below this line
 PROXY_URL = "{local_host}:{local_port}".format(

File src/static/default.css

-body        { background: beige; margin: 0; padding: 0;
-              font-family: 'Palatino', Arial,
-              sans-serif; font-weight: 300; font-size: 18px; }
-.box        { width: 800px; margin: 20px auto; padding: 1em 2em;
-              font-size: 150%; line-height: 1.4em;
-              background: white; box-shadow: 0 1px 4px #BED1D4;
-              border-radius: 2px; }
-.error      { background: #E8EFF0; padding: 3px 8px; color: #11557C;
-              font-size: 0.9em; border-radius: 2px; }
-.title      { margin: 1.25em; text-align: center; line-height: 1.2em;
-              color: brown; font-family: 'Georgia'; }
-.source     { font-weight: lighter; font-size: 20px; color: black;
-              text-align: right; float: right; }
-.backhome a { text-decoration: none; }
-.content h1,
-.content h2,
-.content h3 { font-weight: normal; font-family: 'Georgia'; }
-.content a  { color: #11557C; }
-.content img{ float: left; margin: 1em; }
-.match      { font-weight: bold; }

File src/static/homepage.css

 a       { color: #11557C; }
 h1, h2, h3
         { margin: 0; color: #11557C; font-weight: normal; }
-h1 a    { text-decoration: none; }
+h1 img  { float: right; }
 .tagline{ color: #888; font-style: italic; margin: 0 0 20px 0; }
 .error  { background: #E8EFF0; padding: 3px 8px; color: #11557C;
           font-size: 0.9em; border-radius: 2px; }

File src/static/info.png

Added
New image

File src/static/themes/default.css

+body        { background: beige; margin: 0; padding: 0;
+              font-family: 'Palatino', Arial,
+              sans-serif; font-weight: 300; font-size: 18px; }
+.box        { width: 800px; margin: 20px auto; padding: 1em 2em;
+              font-size: 150%; line-height: 1.4em;
+              background: white; box-shadow: 0 1px 4px #BED1D4;
+              border-radius: 2px; }
+.error      { background: #E8EFF0; padding: 3px 8px; color: #11557C;
+              font-size: 0.9em; border-radius: 2px; }
+.title      { margin: 1.25em; text-align: center; line-height: 1.2em;
+              color: brown; font-family: 'Georgia'; }
+.source     { font-weight: lighter; font-size: 20px; color: black;
+              text-align: right; float: right; }
+.backhome a { text-decoration: none; }
+.content h1,
+.content h2,
+.content h3 { font-weight: normal; font-family: 'Georgia'; }
+.content a  { color: #11557C; }
+.content img{ float: left; margin: 1em; }
+.match      { font-weight: bold; }

File src/static/themes/werkzeug.css

+body        { background: #E8EFF0; margin: 0; padding: 0;
+              font-family: 'Helvetica Neue', Arial,
+              sans-serif; font-weight: 300; font-size: 18px; }
+.box        { width: 700px; margin: 20px auto; padding: 1em 2em;
+              font-size: 150%; line-height: 1.25em;
+              background: white; box-shadow: 0 1px 4px #BED1D4;
+              border-radius: 2px; }
+.error      { background: #E8EFF0; padding: 3px 8px; color: #11557C;
+              font-size: 0.9em; border-radius: 2px; }
+.title      { margin: 1.25em; text-align: center; line-height: 1.2em;
+              font-weight: normal; color: #11557C; }
+.source     { font-weight: lighter; font-size: 20px; color: black;
+              text-align: right; float: right; }
+.backhome a { text-decoration: none; }
+.content h1,
+.content h2,
+.content h3 { font-weight: normal; }
+.content a  { color: #11557C; }
+.content img{ float: left; margin: 1em; }
+.match      { font-weight: bold; }

File src/static/werkzeug.css

-body        { background: #E8EFF0; margin: 0; padding: 0;
-              font-family: 'Helvetica Neue', Arial,
-              sans-serif; font-weight: 300; font-size: 18px; }
-.box        { width: 700px; margin: 20px auto; padding: 1em 2em;
-              font-size: 150%; line-height: 1.25em;
-              background: white; box-shadow: 0 1px 4px #BED1D4;
-              border-radius: 2px; }
-.error      { background: #E8EFF0; padding: 3px 8px; color: #11557C;
-              font-size: 0.9em; border-radius: 2px; }
-.title      { margin: 1.25em; text-align: center; line-height: 1.2em;
-              font-weight: normal; color: #11557C; }
-.source     { font-weight: lighter; font-size: 20px; color: black;
-              text-align: right; float: right; }
-.backhome a { text-decoration: none; }
-.content h1,
-.content h2,
-.content h3 { font-weight: normal; }
-.content a  { color: #11557C; }
-.content img{ float: left; margin: 1em; }
-.match      { font-weight: bold; }

File src/templates/documentation.html

+{% extends "layout.html" %}
+{% block title %}Documentation{% endblock %}
+{% block body %}
+  <h1 class="backhome"><a href=/>← <img src="/static/home.png" alt="Home" /></a></h1>
+  <h2 class="title">Documentation</h2>
+  <div class="content">
+    <h2>Usage</h2>
+    <p>When you hit the homepage of the service, there are 3 possibilities:</p>
+    <ul>
+      <li>pasting an URI to read the content and only the content</li>
+      <li>searching for a term in your browsing archives (you need to browse a few URIs before it becomes useful, obviously)</li>
+      <li>droping the bookmarklet in your topbar to instantly access this service when you reach an article with hard to read content</li>
+    </ul>
+    <p>When you're reading an article, you can always reach the original page via links on the header and the footer. The link at the top allows you to go back to the welcome page.</p>
+
+    <h2>Themes</h2>
+    <p>There are a few themes available, see <code>src/static/themes/</code> and you can easily create your own, just drop your custom <acronym>CSS</acronym> in this folder and modify the <code>CSS_THEME</code> setting (see below).</p>
+    <p>The easiest way to proceed is to copy an existing theme in order to know class names and so on. Do not hesitate to share your theme via pull-request!</p>
+
+    <h2>Settings</h2>
+    <p><code>LOCAL_HOST</code> and <code>LOCAL_PORT</code> define the host and port to launch your service. Pro-tip: hack your <code>/etc/hosts</code> file to setup your own domain.</p>
+    <p><code>FORCE_REFRESH</code> setting is mainly for development usage, when you fill the database with wrong data it'll erase it if you hit the same <acronym>URI</acronym> and refill it with fresh data.</p>
+    <p><code>CSS_THEME</code> is a string with the name of the <acronym>CSS</acronym> file (without <code>.css</code>) you put in your theme folder (<code>src/static/themes/</code>).</p>
+    <p><code>REDIS_HOST</code> and <code>REDIS_PORT</code> are useful if you don't run the default configuration.</p>
+    <p><code>WHOOSH_INDEX</code> is the name of the folder to store Whoosh's index.</p>
+    <p><code>USE_DEBUGGER</code> and <code>USE_RELOADER</code> are mainly for debugging purpose, set those to <code>True</code> if you're familiar with Werkzeug.</p>
+    <p>Do not modify the <code>PROXY_URL</code> setting unless you know what you're doing!</p>
+
+    <h2>Architecture</h2>
+    <p><code>print("Hello developers!")</code></p>
+    <p>The code has been splited in a few files:</p>
+    <ul>
+      <li><code>launcher.py</code> is creating the <acronym>WSGI</acronym> app, not really interesting</li>
+      <li><code>browser.py</code> contains Werkzeug URIs and views</li>
+      <li><code>storage.py</code> deals with persistence in both Redis and Whoosh, the parsing of the <acronym>HTML</acronym> is done in that class too</li>
+      <li><code>utils.py</code> contains useful functions used as Jinja's filters or helpers.</li>
+      <li><code>settings.py</code> defines custom settings to run the application.</li>
+      <li><code>/static/</code> contains <acronym>CSS</acronym> files (with themes) and images.</li>
+    </ul>
+    <p>Once you know the code dispatching, let's talk about data's dispatching! When you submit a <acronym>URI</acronym>:</p>
+    <ul>
+      <li>the web page will be retrieved by <a href="http://docs.python-requests.org/">requests</a> and parsed with <a href="http://pypi.python.org/pypi/readability-lxml">readability</a></li>
+      <li>the content of the web page is modified to create local links for each link in that content in order to be able to browse from content to content</li>
+      <li>the content is stored in both <a href="http://redis.io/">Redis</a> and <a href="http://whoosh.ca/">Whoosh</a>, the first one is used to cache it across requests, the second to index content and allow search across browsing history</li>
+    </ul>
+    <p>That's it for now, please submit enhancement's issues if you need more information here to participate, the code should be well documented so dig in :-).</p>
+  </div>
+{% endblock %}

File src/templates/layout.html

   <head>
     <title>{% block title %}{% endblock %}</title>
     <link rel="shortcut icon" href="/static/favicon.ico">
-    <link rel=stylesheet href=/static/{{ theme }}.css type=text/css>
+    <link rel=stylesheet href=/static/themes/{{ theme }}.css type=text/css>
     {% block extrahead %}{% endblock extrahead %}
   </head>
   <body onload="document.getElementById('url').focus()">

File src/templates/new_url.html

 {% block title %}Browse content{% endblock %}
 {% block extrahead %}<link rel=stylesheet href=/static/homepage.css type=text/css>{% endblock extrahead %}
 {% block body %}
-  <h1>Browser</h1>
-  <p class=tagline>Browse content from bloated web pages.
+  <h1>Browser <a href="/doc"><img src="static/info.png" /></a></h1>
+  <p class=tagline>Browse content from bloated web pages.</p>
   <h2>Submit URL</h2>
   <form action="" method=post>
     {% if error %}