Как внести свой вклад в varnish-cache.org

Репозиторий Git

Содержание веб-сайта хранится в github по адресу:

https://github.com/varnishcache/homepage

Чтобы внести свой вклад, создайте форк проекта и отправьте нам запрос на включение изменений.

Sphinx и RST

Источники веб-сайта написаны на RST – reStructuredText, формате документации, первоначально разработанном для Python (и также используемом в дистрибутиве Varnish, а также для форматирования документов VMOD). Sphinx используется для рендеринга веб-страниц из источников RST.

Поэтому вам необходимо изучить разметку RST и Sphinx; и вам необходимо установить Sphinx, чтобы протестировать рендеринг на вашей локальной системе.

Makefile

Генерация веб-контента из исходных данных управляется Makefile в каталоге R1 репозитория:

$ cd R1
$ make help
Please use `make <target>' where <target> is one of
html       to make standalone HTML files
dirhtml    to make HTML files named index.html in directories
singlehtml to make a single large HTML file
pickle     to make pickle files
json       to make JSON files
htmlhelp   to make HTML files and a HTML help project
qthelp     to make HTML files and a qthelp project
applehelp  to make an Apple Help Book
devhelp    to make HTML files and a Devhelp project
epub       to make an epub
latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
latexpdf   to make LaTeX files and run them through pdflatex
latexpdfja to make LaTeX files and run them through platex/dvipdfmx
text       to make text files
man        to make manual pages
texinfo    to make Texinfo files
info       to make Texinfo files and run them through makeinfo
gettext    to make PO message catalogs
changes    to make an overview of all changed/added/deprecated items
xml        to make Docutils-native XML files
pseudoxml  to make pseudoxml-XML files for display purposes
linkcheck  to check all external links for integrity
doctest    to run all doctests embedded in the documentation (if enabled)
coverage   to run coverage check of the documentation (if enabled)

В большинстве случаев вам просто нужно make html для тестирования рендеринга вашего вклада.

Тема оформления alabaster

Мы используем тему alabaster, которую, возможно, вам нужно добавить в вашу локальную установку Python:

$ sudo pip install alabaster

Мы обнаружили, что вам может потребоваться связать каталог установки пакета alabaster с каталогом, где Sphinx ожидает найти темы. Например (на моей машине), alabaster был установлен в:

/usr/local/lib/python2.7/dist-packages/alabaster

И Sphinx ожидает найти темы в:

/usr/share/sphinx/themes

Таким образом, чтобы цели make выполнялись успешно:

$ cd /usr/share/sphinx/themes
$ ln -s /usr/local/lib/python2.7/dist-packages/alabaster

Протестируйте рендеринг

Теперь вы можете редактировать содержимое в репозитории сайта и тестировать рендеринг, вызвав цели make в каталоге R1:

$ cd $REPO/R1
$ make html
sphinx-build -b html -d build/doctrees   source build/html
Running Sphinx v1.2.3
loading pickled environment... done
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] tips/contribdoc/index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] tips/index
writing additional files... genindex search
copying static files... done
copying extra files... done
dumping search index... done
dumping object inventory... done
build succeeded.

После успешной сборки недавно сгенерированный контент сохраняется в каталоге R1/source/build, чтобы вы могли посмотреть его в браузере.

Отправьте нам запрос на включение изменений

Когда ваш вклад будет успешно компилироваться, отправьте нам PR, мы будем рады услышать от вас!