Dependencies

ucomment must run on a web server. The following programs are assumed to be installed on that server:

• Python 2.6 or better (it may work with Python 2.5, but it has not been tested)

• Django 1.2.1, or better, and its dependencies (earlier versions may work also)

• Sphinx 1.0.7, or better, and its dependencies.

• Mercurial 1.6.2, or better (earlier versions may work also)

Detailed installation instructions

1. Create a Django project with django-admin.py startproject ucommentsite or use an existing project.

2. Inside the Django project, clone the latest version of the ucomment Django application:

   hg clone http://bitbucket.org/kevindunn/ucommentapp

   After this step your Django project directory should like similar to:

   /__init__.py
   /manage.py
   /settings.py
   /ucommentapp/   <--- subdirectory of files just cloned above
   /urls.py

3. The next group of settings will change lines in your Django project’s settings.py file.

   • Add the ucomment application to your Django project’s INSTALLED_APPS section. For example:

     INSTALLED_APPS = (
             'django.contrib.auth',
             'django.contrib.contenttypes',
             ....
             'ucommentapp',
             ...
             )

   • If this is a new Django project, then also edit the database settings.

   • Ensure that you have a valid email address under the ADMINS section. ucomment will send an email to that address should anything go wrong with the application.

   • The ucomment also requires that you set these 5 entries in the settings.py file. Examples are given so you can see what is expected.

     EMAIL_HOST = 'smtp.example.com'
     EMAIL_PORT = 25
     EMAIL_HOST_USER = 'yourname'
     EMAIL_HOST_PASSWORD = 'your_password'
     EMAIL_FROM = 'Web comments <web.comments@example.net>'
     

   • You should set your MEDIA_URL and MEDIA_ROOT settings to tell Django where your media files are served from.

4. Cut and paste all lines from ucommentapp/project-urls-append.py into the bottom of your Django project’s urls.py file. You can of course edit the URL where the document will be hosted. The default setting is:

   (r'^document/', include('ucommentapp.urls')),
   

   If you would like to host the document at mydoc, then change this to:

   (r'^mydoc/', include('ucommentapp.urls')),
   

   Then the document will be available at http://example.com/mydoc/. If you prefer to host the documentation at the root of the website, such as http://example.com/, then use:

   (r'', include('ucommentapp.urls')),
   

   in your Django project’s urls.py file.

5. If you changed the default settings in the previous step, then you must also make these two changes:

   1. In the Javascript file, ucommentapp/media/ucomment.js: look for the line that refers to URL_VIEWS_PREFIX, and adjust it.

   2. Also change the line in ucommentapp/conf/settings.py: look for the line that refers to the url_views_prefix setting.

6. Now it is time to create the database tables for this application. Run the following command from the Django project directory:

   manage.py syncdb

7. Next, spend some time editing the ucomment settings in ucommentapp/conf/settings.py. There are several settings that you need to adjust to let the application know about your document and how you prefer users to interact with it.

   That settings file has many comments to help you along.

8. Now you should be ready to publish your document for the first time.

   Starting a new document

   • At the command line:

     > sphinx-quickstart

     and follow the prompts from Sphinx.

   • The directory structure on your hard drive should appear something like:

     _build/
     conf.py
     index.rst
     Makefile
     _static/
     _templates/

   • Your master document file is called index.rst, if you accepted the defaults when running sphinx-quickstart.

     Edit your master document as shown:

     Before:

     Various text.
     
     Contents:
     
     .. toctree::
             :maxdepth: 2
     
     Other text

     After:

     Various text.
     
     Contents:
     
     .. toctree::
             :maxdepth: 2
     
             section1
     
     
     Other text.

     The section1 tells Sphinx to include the content of the file called section1.rst into your document. You can of course add more than one file, and you can use any names you like for the files.

   • Now create and edit the section1.rst text file to contain your document. It must be valid Sphinx markup.

   • Place your entire document under revision control:

     >> hg init
     >> hg add conf.py index.rst Makefile section1.rst
     >> hg commit -m"First commit of my document"

   • Now continue on with the instructions below.

   Using an existing document already under revision control

   • Your document files must all contain valid Sphinx markup.

   • You will need the Sphinx-generated conf.py file for your document, that you have likely customized.

   • In addition, all files, images, and other content that make up your document must be available in the directory containing your document.

   • All the materials from the 3 previous points must be under version control in a single repository. If you are unfamiliar with revision control, please visit this helpful site.

   • ucomment (currently) supports the Mercurial distributed version control system (DVCS). We definitely want to support other DVCS’s, and the code is set up to allow this to be added by interested developers.

   • The repository containing your document can be on your webserver, or available remotely, from another server (though this will add some latency to your ucomment site, and should be avoided).

   • You will need to adjust your conf.py file to add a custom Sphinx extension for ucomment. Add the following lines, near the top of your conf.py file, anywhere after the extensions = [...] list. Please only edit the last line shown below, all other lines must be included exactly as-is.

     # ucomment extension
     sys.path.append(os.path.abspath(os.getcwd()))
     extensions.append('ucomment-extension')
     html_translator_class = 'ucomment-extension.ucomment_html_translator'
     
     # Point to your Django application, which contains all
     # the other settings required.
     ucomment = {}
     ucomment['django_application_path'] = '/path/to/Django/project/ucommentapp'
     

     The last line points to your installation of ucomment, set in step 2 above. Once it knows this location, it will be able to use all other settings you specified earlier in your ucommentapp/conf/settings.py file.

9. To start publishing your document, start your Django server, or, if you are in development mode: run the built-in Django development server:

   manage.py runserver

10. Visit the publish/update page for this application. The link is http://example.com/document/_admin. Obviously you should replace example.com with you own site address, and also replace the document part only if you adjusted settings in step 4 and 5 above.

    Click on the link to publish/update the document. This step calls Sphinx, which should be installed on your web server, to convert the RST source files to HTML.

    That HTML is added to the Django database, and served to the website visitors from Django.

11. On your web server, and only after you have published the document for the first time (previous step), you should go check the local document repository.

    Go to the location on your web server where you have the ucomment application; e.g. ... /my-django-project/ucommentapp/

    You will see a new directory was created by ucomment called document_compile_area - this is the web server’s clone of your document, and the RST files are modified slightly when users comment on your document.

    These changes will be pushed back to the source repository automatically. But if your source repo is on a remote site, or requires credentials to push to, then you must add settings to allow this to occur without manual intervention.

    For Mercurial, this simply requires that you add a few lines in the ucommentapp/document_compile_area/.hg/hgrc file. Something similar to:

    [auth]
    
    repo.prefix = hg.example.com/mercurial
    repo.username = foo
    repo.password = bar
    repo.schemes = https
    
    [paths]
    
    default = ......
    

    For more details see the Mercurial website.

    If you use a remote server for your document’s source, please ensure that you can get reasonable response times for pulling and pushing changes.

    To test if your settings are correct, make a minor change to the local RST document files and commit the change. Then at the command prompt write write hg push and that change should be pushed back to the source repo without any user intervention (e.g. entering usernames and passwords).

12. Once your document is published, it will be available at http://example.com/document/contents

    unless you used a different setting for master_doc in your document’s conf.py file.

13. If you HTML looks “ugly”, it is because we haven’t yet added the CSS and Javascript styling elements. Copy, or symlink, these files to the MEDIA_ROOT directory you specified in your Django settings.py file.

    ucommentapp/media/ucomment.js
    ucommentapp/media/ucomment.css
    ucommentapp/media/*.png

    Feel free to adjust any of the settings in the CSS or Javascript files to match your sites’ appearance.

14. If are running ucomment at the root of your website, i.e. you adjusted the url_views_prefix setting in step 4 and 5; then you will also want to set your web server to serve the favicon.ico and robots.txt files. See the Django documentation for details.

15. Now your web visitors should be able to view your document, and comment on any paragraph, figure, source code, tables, in other words, every node in your document is comment-able.