Update contributing docs (#441)

- Skip unneed installation step, but note that it's not needed
- Add help text to the `pyvec-docs` subcommands; refer to that
  from the docs
- Add a tiny summary to README

Author: encukou

CONTRIBUTING.rst

@@ -16,16 +16,26 @@ Instalace
 Když toho upravujete víc, nebo máte zálusk na nějaké složitější kejkle, je lepší mít materiály nainstalované na svém počítači. Bude k tomu potřeba `uv <https://docs.astral.sh/uv/>`_:
 
 #. Stáhněte projekt: ``git clone https://github.com/pyvec/docs.pyvec.org.git``
-#. Nainstalujte: ``uv sync --group=dev``
+#. Přejděte do něj: ``cd docs.pyvec.org``
+
+.. note::
+
+    O instalaci, včetně správy virtuálního prostředí, se postará
+    ``uv`` automaticky při prvním spuštění.
 
 Běžná práce
 -----------
 
-#. Ve virtuálním prostředí spusťte projekt: ``uv run pyvec-docs build``
+#. Spusťte projekt: ``uv run pyvec-docs watch``
 #. Otevřete si v prohlížeči `<http://127.0.0.1:8000>`_
 #. V editoru upravujete texty a v prohlížeči si kontrolujete výsledek
 #. Projekt zastavíte v terminálu pomocí :kbd:`Ctrl+C`
 
+Další užitečné nástroje, např. na jednorázové sestavení nebo na
+:ref:`generování stránek <generate_files>`,
+najdete spuštěním ``pyvec-docs`` bez podpříkazu: ``uv run pyvec-docs``
+
+
 Markdown
 ^^^^^^^^
 

README.rst

@@ -8,3 +8,14 @@ Jejich cílem je poskytnout materiály a *know-how* pro pořadatele a částečn
 i účastníky (např. kouče) různých akcí, jako jsou srazy, workshopy, kurzy.
 
 Dokumentace je tvořena jako `otevřená <https://cs.wikipedia.org/wiki/Otev%C5%99en%C3%BD_software>`__, do jejího zdrojového kódu a textů může kdokoliv navrhovat změny. Texty a obrázky těchto materiálů jsou uvolněny pod licencí `CC BY-SA 4.0 <https://creativecommons.org/licenses/by-sa/4.0/deed.cs>`__.
+
+
+Přispívání
+----------
+
+Návod na přispívání je `na webu <https://docs.pyvec.org/contributing.html>`__
+a v souboru ``CONTRIBUTING.rst``.
+Stručně:
+
+* Obsah lze upravovat `online <https://github.com/pyvec/docs.pyvec.org>`_ pomocí ikony s tužkou.
+* Lokální spuštění: ``uv run pyvec-docs`` (vypíše stručnou nápovědu)

src/pyvec_docs/cli.py

@@ -18,6 +18,7 @@ def main() -> None:
 
 @main.command()
 def test() -> None:
+    """Run the tests"""
     try:
         subprocess.run(["pytest"], check=True)
     except subprocess.CalledProcessError:
@@ -26,6 +27,7 @@ def test() -> None:
 
 @main.command()
 def build() -> None:
+    """Build the documentation into the build directory"""
     try:
         subprocess.run(["sphinx-build", "-nWaE", "docs", "build"], check=True)
     except subprocess.CalledProcessError:
@@ -34,6 +36,7 @@ def build() -> None:
 
 @main.command()
 def watch() -> None:
+    """Serve documentation on a local webserver, rebuild on changes"""
     try:
         subprocess.run(["sphinx-autobuild", "-nWaE", "docs", "build"], check=True)
     except subprocess.CalledProcessError:
@@ -63,6 +66,7 @@ def gen_grants(
     github_url: str,
     github_token: str,
 ) -> None:
+    """Generate grants.rst (needs authorization token)"""
     github_headers = {
         "Accept": "application/vnd.github.squirrel-girl-preview",
         "Authorization": f"token {github_token}",
@@ -145,6 +149,7 @@ def gen_boards(
     template_path: Path,
     output_path: Path,
 ) -> None:
+    """Generate boards.rst"""
     boards = load_boards()
     tpl = Template(template_path.read_text())
     output_path.write_text(tpl.render(boards=boards))