Saturday, October 11, 2014

Local Instance of READTHEDOCS


I've been struggling in setting up a local instance of readthedocs (rtd) with Solr for searching.
After lots of testing I've come up with the following procedure to have a local instance of Read The Docs and a working Solr. 

Bare in mind that this procedure is not for production instances!

I did this procedure on a clean Ubuntu 14.04 desktop installation.

Prerequisites

Make sure that you install the following packages:
  • python-virtualenv
  • git
  • curl
  • libxml2-dev
  • libxslt1-dev
  • zlib1g-dev
  • openjdk-7-dev
Most of the steps can be found in the documentation of readthedocs.org. Here I will show you the steps I followed.

Steps

Use three terminals to get this thing working, one for running readthedocs, one for Solr and one for building the files and saving them into Solr.
  1. Create a virtualenv and activate it:
    virtualenv venv
    source venv/bin/activate
  2. Create a folder in venv and clone the readthedocs repository:
    cd venv
    mkdir sources
    git clone https://github.com/rtfd/readthedocs.org.git
  3. Install rtd:
    cd readthedocs.org
    pip install -r pip_requirements.txt
  4. Build the rtd database:
    cd readthedocs
    ./manage.py syncdb
    Create a superuser when requested.
  5. Migrate:
    ./manage.py migrate
  6. Set Solr as local backend in the rtd settings:
    1. Go into the settings directory and update the files __init__.py, base.py, and sqlite.py.
    2. Update the parameter HAYSTACK_CONNECTIONS with:
      HAYSTACK_CONNECTIONS = {
          'default': {
              'ENGINE': 'haystack.backends.solr_backend.SolrEngine',
              'URL': 'http://127.0.0.1:8983/solr',
          }
      }
  7. Open your second terminal and create and activate virtualenv, identical as in step 1. 
  8. Download and extract Solr 3.5.0:
    cd venv/sources/
    curl -O http://archive.apache.org/dist/lucene/solr/3.5.0/apache-solr-3.5.0.tgz
    tar xvzf apache-solr-3.5.0.tgz && SOLR_PATH=`pwd`/apache-solr-3.5.0/example
  9. Install pysolr and pyquery: pip install pysolr && pip install pyquery.
  10. Go to the directory venv/sources/readthedocs.org/readthedocs.
  11. Build a Solr-schema: ./manage.py build_solr_schema > $SOLR_PATH/solr/conf/schema.xml.
  12. Go back to the directory venv/sources/apache-solr-3.5.0/example and start solr:
    java -jar start.jar
  13. In your first terminal, go to the directory venv/sources/readthedocs.org/readthedocs and start the rtd instance:
    ./manage runserver
You are now able to log in to RTD with the created superuser. Go to 127.0.0.1:8000 for the RTD instance or to 127.0.0.1:8000/admin for the Django settings.

The created setup needs to be filled with data, you can do this via a third terminal and add some projects.
In this third terminal, create a virtualenv as described above and then add projects as follows:
  1. Go to venv/sources/readthedocs.org/readthedocs.
  2. Add a project with the following command: ./manage.py update_repos
    • pip
    • haystack
    • tastypie
    • kong
    • read-the-docs
    • ...
  3. Add the content to Solr, to be able to search in the documentation:
    ./manage.py build_files.
When you add other projects, either via the above command, or by importing them via the rtd web interface, run this last command to make them available through Solr.

You have now a local instance of RTD with Solr as search engine.

A lot more needs to be done in order to make it ready for production environments. Solr should be working in a container, a webserver is required, automation needs to be set up for new projects to become automatically available, and so on. Hope to get this done in the near future.

Until then, have fun with your local ReadTheDocs!

Friday, July 4, 2014

Sphinx, ReadTheDocs and Dashes

For my documentation, I often have to document *nix command-line stuff. No problem until you have to document options that come along with commands.

In Sphinx you have the ":command:" directive to show commands in a uniform way. However, if the command has options that are indicated with a double-dash, the double-dash is by default converted to a single dash.

For example: ":command:`./mycommand.py --myoptions options.ini`" would render as "./mycommand.py -myoptions option.ini". Very annoying indeed, since people tend to copy/paste commands and then they are surprised that "it doesn't work".

Weird thing is that in my local Sphinx setup, using 1.3a0, the rendering is correct, but in the default Sphinx version 1.2.x (if I'm not mistaken, also used by ReadTheDocs), I have the single dash. After looking around on the web, found that the parameter "html_use_smartypants" in the Sphinx conf.py file is the culprit. This parameter is by default disabled, but the smartypants is not disabled by Sphinx and ReadTheDocs itself. This smartypants converts the double dash to a single dash or sometimes en-dash (or em-dash). Since the parameter was commented I didn't take notice of it, but I didn't come to the proper rendering.

To actually disable the smartypants, you have to literally set it to False and then I finally have the correct rendering of my double dash.

# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.

html_use_smartypants = False

/me happy to start the last day of the week.

Wednesday, September 18, 2013

Dear Atlassian


To whom it may concern...

I have been using your Confluence since 2007 and the ease of it was just a joy. Ok, it had its shortcomings, but I could live with them, they didn't annoy me. Confluence, you were easy to learn, you were just a plain text editor, you had enough room for easy customizations. All this made that I could focus on my job, which happens to be technical writing in software companies. My last version I worked with was 3.5, but then came August 2013.
In that month I started at a new company where they use a 5.x version. Now one (yes only ONE) month later and you make me already sick.

I suppose that the function of the new interface is to be more user-friendly than a plain text editor. I have to admit, inserting macros is a step forward, same for inserting warnings, tips, notes,...  BUT, what the hell have you been doing with lists? To insert or add a numbered item to an existing numbered list, you have to be a magician. Luckily CTRL-Z does work in your editor.
And why can't I use a bulleted list in for example a warning block, when this block is in a numbered list? Can you give me an explanation for that?

Table of contents macro, maybe it's not your fault, but why do you use different styles? A table of contents is supposed to have a consistent layout, but why some items are in bold, others in a large font-size and some others in smaller font-size, I really don't see the benefit of it.

Apart from my aforementioned vexations, I have a last one to mention. When you create a PDF of a space, the links in the PDF document refer to the online documentation, whereas in 3.5 and earlier versions, they referred to the page inside the PDF. Did this function moved to more comfy places, is it playing trollface, ... You were in there and now you're gone, how hard can it be to get it back?
This bug is reported 721 days ago (27 September 2011, yes that's almost TWO years). It surprises me that you do go to the selected section when you click an item in the table of contents. So where's the difference? I don't see any so just FIX IT, and if you can't fix it, FIX HARDER!

I can't get the idea out of my head that you, Atlassian, are becoming like that other well-known tech giant, founded by Bill Gates. That company too is very good at ditching good parts of software, creating new versions that annoys people, and not listening to their customers.

Perhaps our annual fee is just 0,00000005% of your annual turnover, which makes us just a 'no-influence-at-all' company for you, but I just don't care. Perhaps that some day I will embrace you again with love and care, but right now, I'm ditching you.

Sincerely

Friday, August 16, 2013

Good to know

I recently started working on MacBook Pro, you have to try it all. In the past I had Windows and Ubuntu, so now the time has come to try OS X. Just like every other OS, OS X also has annoyances, of which iTunes is one of my biggest annoyance. Did they replace that team already? Unfortunately you sometimes need it, so I can't get rid of it.

As default music player I now try Songbird and added the keyboard shortcut add-on, which works perfectly. But the downside is that every time you hit a music key (next, previous, play/pause), it also launches iTunes.

The easiest way to get rid of this behavior was nicely noted in the following post:

http://gavinroy.com/posts/disabling-default-itunes-launch-behavior-with.html

Basically, you just need to execute:

launchctl unload -w /System/Library/LaunchAgents/com.apple.rcd.plist

No more, no less.

Friday, June 21, 2013

Thunderbird configureren voor verzenden mails via Telenet account

Toen ik mijn gsm wou instellen om e-mails te ontvangen en versturen via mijn telenet account, kon ik de mails wel ontvangen, maar niet versturen. Ik kon enkel mails versturen als ik op het telenet netwerk zat (wifi of via telenet gsm-abonnement).
Na enig zoekwerk, bleek dat ik dus TLS moest gebruiken en authenticated SMTP om mails te kunnen versturen. Dit direct ook eens gecontroleerd op mijn computer, want ook daar kon ik geen mails versturen via mijn telenet account.

In Thunderbird (getest met versie 17.0.6):

  1. Via Edit > Account Settings, selecteer Outgoing Server (SMTP) in de linker kolom.
    Dit is afhankelijk van operating systeem en taalinstellingen!
  2. Klik op Add en vul in/selecteer de opties zoals aangegeven in de afbeelding onderaan.
  3. Bij gebruikersnaam, geef je je Telenet gebruikers-ID in, meestal bestaande uit 1 letter gevolgd door 6 cijfers zoals in de afbeelding.
Je zou nu zonder problemen mails moeten kunnen versturen, zelfs als je geen gebruik maakt van een Telenet netwerk.

Tuesday, May 21, 2013

How to close xml tags easily in VIM

From ViM 7.3 onwards, most of the common programming languages are supported (/usr/share/vim/vim73/autoload/...). To make them work automatically, update your vimrc with:


autocmd FileType python set omnifunc=pythoncomplete#Complete
autocmd FileType javascript set omnifunc=javascriptcomplete#CompleteJS
autocmd FileType html set omnifunc=htmlcomplete#CompleteTags
autocmd FileType css set omnifunc=csscomplete#CompleteCSS
autocmd FileType xml set omnifunc=xmlcomplete#CompleteTags
autocmd FileType php set omnifunc=phpcomplete#CompletePHP
autocmd FileType c set omnifunc=ccomplete#Complete





Use CTRL+ X O to close tags after typing the start of the closing tags.


For example:

This is a sample paragraph </ CTRL +X O will automatically complete the closing tag.

Simple as that

More information on configuring ViM: http://newbiedoc.sourceforge.net/text_editing/vim.html

Thursday, February 21, 2013

USB connection on Galaxy S3 Mini

Lately my galaxy s3 mini phone was not detected through USB. This is quite annoying... to say the least.

I thought a reboot of my phone would solve the problem, but guess what, it didn't.
I checked the cable, used different ports on my pc and other computers, used different cables, nothing worked, it only started to charge the battery.

I own this phone for only a couple of weeks, so perhaps this thing needed a repair under guarantee. But of course this would take weeks before having it back, so I called my best friend as help.

Google offered me this link http://android.stackexchange.com/questions/35313/unable-to-connect-galaxy-s3-to-pc-via-usb

Most of the links referred to Windows drivers but I'm not a Windows user. However, scrolling down led me to a very simple solution:

*#7284# to access PhoneUtil 

 and select PDA in both sections. Reset phone and that's it.

Credits to the user "eidolon" from Australia.

The only thing is that I don't know how I got in this situation... but at least now I know how to solve it.