From 5a2478fd2cb5ef7b7e25f9570b366c719e925ddc Mon Sep 17 00:00:00 2001 From: Berker Peksag Date: Wed, 4 Mar 2015 08:51:43 +0200 Subject: [PATCH] Update installation guide to Django 1.7 and move it into docs/. --- docs-requirements.txt | 3 + docs/Makefile | 7 +- docs/source/conf.py | 19 +++-- docs/source/install.rst | 155 +++++++++++++++++++++++++++++++++++++- pydotorg/settings/base.py | 6 ++ tasks.py | 6 ++ 6 files changed, 186 insertions(+), 10 deletions(-) create mode 100644 docs-requirements.txt diff --git a/docs-requirements.txt b/docs-requirements.txt new file mode 100644 index 000000000..2cbb5c285 --- /dev/null +++ b/docs-requirements.txt @@ -0,0 +1,3 @@ +-r dev-requirements.txt + +sphinx_rtd_theme diff --git a/docs/Makefile b/docs/Makefile index ae0e8a0ec..e2ec3320b 100644 --- a/docs/Makefile +++ b/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 ' where 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 diff --git a/docs/source/conf.py b/docs/source/conf.py index e85a29ba5..5349ebb2e 100644 --- a/docs/source/conf.py +++ b/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'), ] diff --git a/docs/source/install.rst b/docs/source/install.rst index 9b8afd0be..b7a5e45fd 100644 --- a/docs/source/install.rst +++ b/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 \ No newline at end of file + $ 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 + $ source /bin/activate + +But you can also use your existing virtualenv and virtualenvwrapper:: + + $ virtualenv --python=python3.3 + $ mkvirtualenv --python=python3.3 + +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 `_ +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 + ^ + 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 `_. + +Freetype 2.5.3 is known to work with this repository:: + + $ ln -s /usr/local/include/freetype2 /usr/local/include/freetype diff --git a/pydotorg/settings/base.py b/pydotorg/settings/base.py index e40068fe2..fb6687e27 100644 --- a/pydotorg/settings/base.py +++ b/pydotorg/settings/base.py @@ -165,6 +165,12 @@ ] +# Fixtures + +FIXTURE_DIRS = ( + os.path.join(BASE, 'fixtures'), +) + ### Testing SKIP_NETWORK_TESTS = True diff --git a/tasks.py b/tasks.py index 0d8c18e04..8d37fef36 100644 --- a/tasks.py +++ b/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')