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