1.. _Sphinx: http://www.sphinx-doc.org
2.. _Read the Docs: https://docs.zeek.org/projects/package-manager
3.. _GitHub: https://github.com/zeek/package-manager
4.. _Google Style Docstrings: http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
5.. _zeek-aux: https://github.com/zeek/zeek-aux
6.. _PyPi: https://pypi.python.org/pypi
7
8Developer's Guide
9=================
10
11This a guide for developers working on the Zeek Package Manager itself.
12
13Versioning/Releases
14-------------------
15
16After making a commit to the *master* branch, you can use the
17:program:`update-changes` script in the `zeek-aux`_ repository to automatically
18adapt version numbers and regenerate the :program:`zkg` man page.  Make sure
19to install the `documentation dependencies`_ before using it.
20
21Releases are hosted at PyPi_.  To build and upload a release:
22
23#. Finalize the git repo tag and version with  ``update-changes -R <version>``
24   if not done already.
25
26#. Upload the distribution (you will need the credentials for the 'zeek'
27   account on PyPi):
28
29   .. code-block:: console
30
31      $ make upload
32
33Documentation
34-------------
35
36Documentation is written in reStructuredText (reST), which Sphinx_ uses to
37generate HTML documentation and a man page.
38
39.. _documentation dependencies:
40
41Dependencies
42~~~~~~~~~~~~
43
44To build documentation locally, find the requirements in
45:file:`requirements.txt`:
46
47  .. literalinclude:: ../requirements.txt
48
49They can be installed like::
50
51  pip3 install -r requirements.txt
52
53Local Build/Preview
54~~~~~~~~~~~~~~~~~~~
55
56Use the :file:`Makefile` targets ``make html`` and ``make man`` to build the
57HTML and man page, respectively, or ``make doc`` to build them both.  To view
58the generated HTML output, open :file:`doc/_build/index.html`.  The generated
59man page is located in :file:`doc/man/zkg.1`.
60
61If you have also installed :program:`sphinx-autobuild` (e.g. via
62:program:`pip3`), there's a :file:`Makefile` target, ``make livehtml``, you can
63use to help preview documentation changes as you edit the reST files.
64
65Remote Hosting
66~~~~~~~~~~~~~~
67
68The GitHub_ repository has a webhook configured to automatically rebuild the
69HTML documentation hosted at `Read the Docs`_ whenever a commit is pushed.
70
71Style Conventions
72~~~~~~~~~~~~~~~~~
73
74The following style conventions are (generally) used.
75
76========================== =============================== ===========================
77Documentation Subject      reST Markup                     Preview
78========================== =============================== ===========================
79File Path                  ``:file:`path```                :file:`path`
80File Path w/ Substitution  ``:file:`{<replace_me>}/path``` :file:`{<replace_me>}/path`
81OS-Level Commands          ``:command:`cmd```              :command:`cmd`
82Program Names              ``:program:`prog```             :program:`prog`
83Environment Variables      ``:envvar:`VAR```               :envvar:`VAR`
84Literal Text (e.g. code)   ````code````                    ``code``
85Substituted Literal Text   ``:samp:`code {<replace_me>}``` :samp:`code {<replace_me>}`
86Variable/Type Name         ```x```                         `x`
87INI File Option            ```name```                      `name`
88========================== =============================== ===========================
89
90Python API docstrings roughly follow the `Google Style Docstrings`_ format.
91