GitHub - timparkin/europython.org

Branches Tags

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
build		build
data		data
files		files
images		images
js		js
old-templates/templates		old-templates/templates
scripts		scripts
styles-relative		styles-relative
styles		styles
.gitignore		.gitignore
DESIGN.txt		DESIGN.txt
Makefile		Makefile
README		README
pydotorg.cache		pydotorg.cache

Repository files navigation

You are now in the top-level build directory of the Python web site
(www.python.org). The parent of this directory is referred to as
<buildroot> in the remainder of this document.

This README explains how to build and view a local copy of the web site.
More information on maintaining python.org can be found in the wiki at
https://wiki.python.org/moin/PythonWebsite

Note that while the build process at first seems a little hostile to
Windows users, in actual fact the commands run by "make" are
generally simple and can easily be run from the Windows command line
ig you don't have Cygwin or mingw available to provide "make" and
other Unix-like utility programs.

Installation
---------------

External packages required:

Mako (https://www.makotemplates.org/)
[Note that Mako requires setuptools to install out-of-the-box. You can
also just copy the lib/mako/ tree into your Python's site-packages
directory if you prefer not to install setuptools.]

PyYAML (https://pyyaml.org/wiki/PyYAML)

Docutils (https://docutils.sf.net)

Usage
---------------

In the <buildroot>/build/ directory (this directory):

* Run 'make' to create output in the build/out/ directory.

* Run 'make serve' to run a little web server that will serve the
build/out/ directory on https://localhost:8005/ for testing.

* "make clean" erases the cache file pydotorg.cache and the
build/out/ directory. This target lets you can fully rebuild
everything from scratch to avoid confusion when hacking on the
build system itself.

build.py is the main script. It somewhat impperfectly tries to
track dependencies to avoid unnecessary content rebuild. This isn't
perfect, so you may run into failure to rebuild when changing some
peripheral files other than the *.ht's.

Writing content
-------------------

Each page has a directory of its own. www.python.org/community/jobs/
is built from the contents of the <buildroot>/build/data/community/jobs/
directory, for example.

If you're adding a new page, create a new directory containing a
content.ht file. This file contains a set of RFC-822 headers for
metadata, and the actual page content.

[For Pyramid compatibility: content.rst, nav.yml, and index.yml files
are still supported by the build system, but we're working on phasing
them out. You shouldn't write new ones.]

Allowed values of headers in .ht files (case-insensitive):

Title
Used in <title> tag.

Content-type
How to interpret the rest of the file (options are:
text/html, text/x-rst, text/plain)

Keywords
Included inside a <meta> tag inside the <head>
Description
Included inside a <meta> tag inside the <head>
Javascript
Whitespace separated list of URLs for JavaScript files
(e.g. /js/file1.js /styles/style.js)

Template
Name of template to use for this page; limited to filenames
from the list new-build/*.tmpl. "pydotorg" is the default
page design.

Fragments
Name of fragments of HTML to include in the page alongside
the page's content from the .ht file; limited to filenames
from the list new-build/fragments/*.html.

Quick-links
Indented list of quick links to be placed at the bottom of
the left-hand sidebar.

Nav
Indented list of navigation links for this page; these
are used to assemble the left-hand sidebar.

Document-nav
Indented list of content navigation links for this page.
If provided, these links are placed in a box in the upper
right-hand corner of a page, with a title provided by the
value of the 'Subnav-title' header.
Document-nav-title
Title used for the box containing the content navigation links.
Defaults to 'About'.

Specialized headers:

Using-Python
Indented list of links to put in the 'Using Python' box
of the "homepage" template.

Indented lists are written like this::

Quick Links (2.5) /download/releases/2.5
Documentation {Manuals for Latest Stable Release} https://docs.python.org/
Windows Installer {Easy Installer of Python under Windows} /ftp/python/2.5/python-2.5.msi
Source Distribution {Grab the Source for the Latest Stable Release} /ftp/python/2.5/Python-2.5.tar.bz2
Package Index {Community Collection of Shared Python Modules} /pypi

The last item on each line is a URL or URL path component.

Text between curly brackets {} will be used as the TITLE attribute
of the link.

The rest of the line is the text of the link (between <a>...</a>).

Remaining Tasks
-------------------

Known bugs:
The quick links that appear on the home page (below the left-hand
nav menu) no longer appear on any other page on the site. They did
with Pyramid, and they should still.

Windows users may not have "make" available.
["make" isn't terribly Windows-friendly. How easy would it be to provide
scripts that do the same job as the make limes for Windows users?]