Merge pull request #597 from berkerpeksag/improve-docs

Update installation guide to Django 1.7 and move it into docs/.

docs-requirements.txt

@@ -0,0 +1,3 @@
+-r dev-requirements.txt
+
+sphinx_rtd_theme

docs/Makefile

@@ -2,6 +2,7 @@
 #
 
 # You can set these variables from the command line.
+PYTHON        = python
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
@@ -19,11 +20,12 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) sou
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html htmlview dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html       to make standalone HTML files"
+	@echo "  htmlview   to open the index page built by the html target in your browser"
 	@echo "  dirhtml    to make HTML files named index.html in directories"
 	@echo "  singlehtml to make a single large HTML file"
 	@echo "  pickle     to make pickle files"
@@ -54,6 +56,9 @@ html:
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+htmlview: html
+	$(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')"
+
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo

docs/source/conf.py

@@ -15,6 +15,7 @@
 
 import sys
 import os
+import time
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -49,7 +50,7 @@
 
 # General information about the project.
 project = 'Python.org Website'
-copyright = '2014, Frank Wiles'
+copyright = '%s, Python Software Foundation' % time.strftime('%Y')
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -103,7 +104,13 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+try:
+    import sphinx_rtd_theme
+except ImportError:
+    html_theme = 'default'
+else:
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -132,7 +139,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -202,7 +209,7 @@
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
   ('index', 'PythonorgWebsite.tex', 'Python.org Website Documentation',
-   'Frank Wiles', 'manual'),
+   'Python Software Foundation', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -232,7 +239,7 @@
 # (source start file, name, description, authors, manual section).
 man_pages = [
     ('index', 'pythonorgwebsite', 'Python.org Website Documentation',
-     ['Frank Wiles'], 1)
+     ['Python Software Foundation'], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -246,7 +253,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
   ('index', 'PythonorgWebsite', 'Python.org Website Documentation',
-   'Frank Wiles', 'PythonorgWebsite', 'One line description of project.',
+   'Python Software Foundation', 'PythonorgWebsite', '',
    'Miscellaneous'),
 ]
 

docs/source/install.rst

@@ -1,8 +1,157 @@
 Installing
 ==========
 
-**NOTE:** The Python.org website is built using Django and Python 3
+Using Vagrant
+-------------
 
-It can be installed much like any other Django site.
+You can ignore the below instructions by using Vagrant. After installing::
 
-TODO
+    $ vagrant up
+    $ vagrant ssh
+
+The box will be provisioned by Chef with Python 3.3, a virtualenv set up with
+requirements installed, and a database ready to use. The virtualenv is
+activated upon login.
+
+.. note:: You will need to run ``./manage.py createsuperuser`` to use the admin.
+
+
+Getting started
+---------------
+
+You'll want a virtualenv. Python 3.3 actually includes virtualenv built-in, so
+you can do::
+
+    $ pyvenv-3.3 <env>
+    $ source <env>/bin/activate
+
+But you can also use your existing virtualenv and virtualenvwrapper::
+
+    $ virtualenv --python=python3.3 <env>
+    $ mkvirtualenv --python=python3.3 <env>
+
+And then you'll need to install dependencies::
+
+    $ pip install -r dev-requirements.txt
+
+If you want to install the default Read the Docs theme, you can do::
+
+    $ pip install -r docs-requirements.txt
+
+.. note:: For deployment, you can just use ``requirements.txt``.
+
+In your development environment, you won't need a production ready database, so
+you can use Sqlite3::
+
+    $ export DATABASE_URL=sqlite:///pydotorg.db
+
+You can also add the following setting to ``pydotorg/settings/local.py``::
+
+    DATABASES = {
+        'default': dj_database_url.parse('sqlite:///pydotorg.db')
+    }
+
+Not it's time to run migrations::
+
+    $ ./manage.py migrate
+
+To compile and compress static media, you will need *compass* and
+*yui-compressor*::
+
+    $ gem install bundler
+    $ bundle install
+
+.. note::
+
+   To install *yui-compressor*, use your OS's package manager or download it
+   directly then add the executable to your ``PATH``.
+
+To load all fixture files::
+
+    $ invoke load_fixtures
+
+or::
+
+    $ ./manage.py loaddata fixtures/*.json
+
+If you want to load a specific fixture, use its application name::
+
+    $ ./manage.py loaddata downloads boxes
+
+Finally, start the development server::
+
+    $ ./manage.py runserver
+
+
+Running tests
+-------------
+
+To run the test suite::
+
+    $ ./manage.py test
+
+To generate coverage report::
+
+    $ coverage run manage.py test
+    $ coverage report
+
+Generate an HTML report with ``coverage html`` if you like.
+
+
+Building documentation
+----------------------
+
+To build this documentation locally::
+
+    $ make -C docs/ htmlview
+
+If you don't want to open the browser automatically, you can do::
+
+    $ make -C docs/ html
+
+
+Useful commands
+---------------
+
+* Create a super user (for a new DB)::
+
+      $ ./manage.py createsuperuser
+
+* Want to save some data from your DB before nuking it, and then load it back
+  in?::
+
+      $ ./manage.py dumpdata --format=json --indent=4 $APPNAME > fixtures/$APPNAME.json
+
+
+Troubleshooting
+---------------
+
+If you hit an error getting this repo setup, file a pull request with helpful
+information so others don't have similar problems.
+
+Python 3.3 and OSX 10.8.2
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Homebrew's recipe for Python 3.3 has some difficulty installing distribute
+and pip in a virtualenv. The `python.org installer for OSX <https://www.python.org/download/>`_
+may work better, if you're having trouble.
+
+Freetype not found on OSX
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    _imagingft.c:60:10: fatal error: 'freetype/fterrors.h' file not found
+    #include <freetype/fterrors.h>
+             ^
+    1 error generated.
+    error: command 'clang' failed with exit status 1
+
+If you've installed *freetype* (``brew install freetype``), you may need
+to symlink version 2 into location for version 1 as mentioned by `this
+Stack Overflow
+question <http://stackoverflow.com/questions/20325473/error-installing-python-image-library-using-pip-on-mac-os-x-10-9>`_.
+
+Freetype 2.5.3 is known to work with this repository::
+
+    $ ln -s /usr/local/include/freetype2 /usr/local/include/freetype

pydotorg/settings/base.py

@@ -165,6 +165,12 @@
 
 ]
 
+# Fixtures
+
+FIXTURE_DIRS = (
+    os.path.join(BASE, 'fixtures'),
+)
+
 ### Testing
 
 SKIP_NETWORK_TESTS = True

tasks.py

@@ -39,3 +39,9 @@ def copy_data_from_staging(keep=False):
 def clear_pycs():
     """ Remove all .pyc files from project directory """
     run("""find {} -name "*.pyc" -delete""".format(BASE_DIR))
+
+
+@invoke.task
+def load_fixtures():
+    """Load all fixture files."""
+    run('./manage.py loaddata fixtures/*.json')