Nächstes DH-Technik-Treffen

Das erste DH-Techniktreffen im Jahr 2019 findet

zum Thema ‚Kollaborativ und plattformunabhängig Präsentationen erstellen“ am 14.2. um 11h im Zentrum für nachhaltiges Forschungsdatenmanagement (Monetastr. 4 ) statt.

 

Interessenten melden sich bitte unter folgender E-Mail-Adresse an:

iris.vogel@uni-hamburg.de oder

im Gitlab

https://gitlab.rrz.uni-hamburg.de/fdm/dh-technik/issues/14

 

Setting up readthedocs in Github (GitLab: should be similar) (Peter Verkinderen)

(see http://tutos.readthedocs.io/en/latest/source/git_rtd.html

http://read-the-docs.readthedocs.io/en/latest/getting_started.html

https://www.youtube.com/watch?feature=player_embedded&v=oJsUvBQyHBs )

STEP 1: LOCALLY:

1. Install sphinx on your machine: pip install sphinx

2. Make documentation folder in the local project folder

3. In command line: go into project folder, and run sphinx-quickstart ; this will start a setup wizard, just follow through and accept the standard responses. This creates a number of files and folders, including the main source file: index.rst (reStructuredText)

4. Make the html: in command line, run make html; this makes the index.html in the _build directory

5. Make a source folder in the documentation folder. To this folder, add an .rst file for every main section you want in your documentation (in my case: quickstart.rst, usermanual.rst, technicalmanual.rst)

NB: these files should not be entirely empty, they need to contain at least a title (underlined with =====)

6. Adapt the table of contents in the index.rst file: add the reference to the .rst files you put in the source folder: e.g.

.. toctree::

  :maxdepth: 3

  source/quickstart

  source/usermanual

  source/technicalmanual

NB: the maxdepth defines how many sublevels that are present in your .rst documents will be visible in the table of contents (so, even if your .rst files have 5 different heading levels, you can choose to show only the headings of the 3 highest levels)

7.  Commit the changes and push them to the remote repository

STEP 2: ON THE READTHEDOCS WEBSITE:

8.   Set up a profile at https://readthedocs.org/

9.   After signing  up, you get to the readthedocs dashboard: https://readthedocs.org/dashboard/

10. Click Import

11. Choose Connect to GitHub (or Connect to GitLab)

12. Click the Plus next to the GitHub repository you want to import

13. Click Next => message: Webhook activated

14. Click Build => online documentation is now built

15. Click View Docs to see the online documentation!

 

STEP 3: ENABLING AUTODOC (LOCALLY)

Sphinx autodoc extracts the docstrings (Python speak for code documentation, between quotation marks immediately after declaring functions/classes/methods/modules) from your code files and brings them together in a nice layout, which can be viewed on Readthedocs.

(see http://www.sphinx-doc.org/en/stable/ext/autodoc.html ,

https://pythonhosted.org/an_example_pypi_project/sphinx.html#full-code-example )

 

  1.  In the Sphinx conf.py file in the root of your project: add ’sphinx.ext.autodoc‘ to the extensions list:
# Add any Sphinx extension module names here, as strings. They can be

# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

# ones.

extensions = ['sphinx.ext.autodoc']

 

  1.  Still in the Sphinx conf.py file: add Napoleon extension to the extensions list (this allows Sphinx to parse docstrings that are not written in formal reStructure Text but in Google or NumPy style; see http://www.sphinx-doc.org/en/stable/ext/napoleon.html#module-sphinx.ext.napoleon ):
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']

 

  1.       Also add the following lines to (the end of) the conf.py file:
# Napoleon settings for Sphinx autodoc:

napoleon_google_docstring = True

napoleon_numpy_docstring = True

napoleon_include_init_with_doc = False

napoleon_include_private_with_doc = False

napoleon_include_special_with_doc = True

napoleon_use_admonition_for_examples = False

napoleon_use_admonition_for_notes = False

napoleon_use_admonition_for_references = False

napoleon_use_ivar = False

napoleon_use_param = True

napoleon_use_rtype = True

 

  1.       Add the path to the root folder in which the modules to be documented are; do this by uncommenting the last three lines in the following, and providing the right path:

 

# If extensions (or modules to document with autodoc) are in another directory,

# add these directories to sys.path here. If the directory is relative to the

# documentation root, use os.path.abspath to make it absolute, like shown here.

#

import os

import sys

sys.path.insert(0, os.path.abspath('..')) # for the folder above the present folder
  1.       Add all paths to the folders in which python modules that are imported in the modules that you are documenting; otherwise, Sphinx cannot access these. In my case:
sys.path.insert(0, os.path.abspath('../modules'))

 

  1.       In the technicalmanual.rst in the source folder, we will now write the reStructuredText code that will direct the building of the documentation (autodoc is in fact semi-automatic, you can decide what exactly you want to include). For each module you want documented, write:
.. automodule:: <filepath>

E.g.:

.. automodule:: modules.jedli_gui
  1.       If you want the classes/functions/methods in your module to be documented as well: write
.. automodule:: modules.jedli_gui

:members:
  1.       Members without docstring will be left out, unless you add the following flag (under :members: ):
:undoc-members:
  1.  Save the technicaldocs.rst file
  2.   Build the docs locally: in the commandline, run make html (from the documentation folder, in which the make.bat file is located)
  3. commit changes and push to remote

 

STEP 4: BUILD THE DOCUMENTATION FROM GITHUB/GITLAB

 

http://docs.readthedocs.io/en/latest/faq.html?highlight=autodoc

  1. enable the virtualenv feature in the Admin page of your readthedocs project:

i.     make a requirements.txt file that contains the folder name of the Python modules that are imported in the Python modules you want to document (in my case, this is a .txt document with only one word: modules

ii.      save this file in the documentation folder of your project; commit and push to remote

iii.    go to the readthedocs dashboard, and click Admin (in my case, this is a  direct link: https://readthedocs.org/dashboard/jedli/edit/)

iii.      click Advanced Settings

iv.     put the name of the requirements file in the “Requirements file” field (keep the “Install your project inside a virtualenv using setup.py install” unchecked)

v.   scroll down and check “Use system packages”

vi.  click submit

13 The docs should now be built.

my files are here:

https://github.com/pverkind/jedli

http://jedli.readthedocs.io/en/latest/

 

(let me know if the description is not clear: peter.verkinderen@uni-hamburg.de)

DH-Technik-Treffen Projektvorstellungen

Das 2. DH-Technik-Treffen im Jahr 2018 findet am 10. April um 12:00h in der Schlüterstraße 51 (Universitätskolleg) Raum 4019 statt.

Es stellt die Projekte der Teilnehmer in den Mittelpunkt. Für die Kurzvorstellungen der einzelnen Projekte stehen ca. 10 Minuten zur Verfügung. Ziel der Sitzung ist ein Überblick über die Themen, Technologien und Herausforderungen zu bekommen, mit welchen die Projektmitarbeiter konfrontiert sind.

Das DH-Technik-Treffen steht allen Interessenten offen. Aufgrund der begrenzten Raumkapazität wird um Anmeldung gebeten (per Mail oder Telefon).

 

DH-Technik-Treffen zu gitlab und nächster Termin

Im DH-Technik-Treffen am 16.1.2018 haben wir uns dem Thema Nutzung von gitlab für Projektmanagement (insb. kanban und Continuous Integration (CI)) gewidment.

Kurzvorstellung: der Passwortmanager LastPass (bzw OpenSource Alternative KeePass)

Termin für das nächste Treffen voraussichtlich:

Datum: 06.02.2018

Zeit: 12:00-14:00h

Thema: Dokumentation 2

Ort: tba (AS-Saal ESA1 (oder Besprechungssaal Monetastraße)

Termin 15.1. -> 16.1. 10h

Aufgrund von Terminkollisionen verschiebt wird das nächste Treffen am:

Dienstag, den 16.1.2018 um 10h stattfinden

Wir treffen und im Akademischen Senatssaal in ESA 1.

Nächster Termin 15.1.2018 (18.12. entfällt)

Das nächste DH-Technik-Treffen wird voraussichtlich am 15.1. 2018 stattfinden. Thema ist der Erfahrungsaustausch zum Arbeiten mit und den Funktionen von gitlab.

Allen Teilnehmern und Interessenten wünschen wir eine frohe Advents- und Weihnachtszeit!

🎄

DH-Technik-Treffen zum Thema Dokumentation

Am 20.11. haben wir uns zum Thema „Dokumentation“ ausgetauscht.

Die wesentlichen Diskussionspunkte waren

  • wie kann man eine niederschwellige Dokumentation erstellen
  • in welcher Sprache (welchen Sprachen?) sollte die Dokumentation erstellt werden
  • Werkzeuge bzw. Formate
    • Wiki:
      • Vorteile: einfache Handhabung, meist bereits vorhanden (Projektmanagement, Versionsmanagement)
      • Nachteile: wird schnell unübersichtlich, Video-Integration nicht bei allen möglich (Gebärdensprache)
    • Doxygen zur Dokumentation, Integration in Redmine
  • Workflow:
    • Dokumentation in der Planung (Nachteil: ggfs. viele Änderungen nötig), nach Fertigstellung
    • Wie kann man Dokumentation aktuell halten?
    • Konventionen zur Erstellung von Dokumentation von Projekten
    • Notwendigkeit eines Pflichtenheft, in welchem zu Anfang die Rollen einzelner Personen festgelegt werden
    • Problem ist der Übergang in den Regelbetrieb
    • Benutzermanual sollte man auch mit dem Code zusammen readthedocs
    • Dokumentations-Workflow in mehreren Phasen
      •  Grundstruktur / Ideen
      • Überprüfung der Dokumentation

gitlab-Neuigkeiten

Am 2.11. gab es ein Treffen im kleinen Kreis zur Versionierung von großen Daten mit git-lfs / borg-backup. Dabei ging es darum, wie man die Einschränkungen in der Versionierung mit git-lfs durch eine Integration von git mit borg-backup vermeiden kann. Das bietet sich insbesondere für große Dateien an, in welchen regelmäßig kleine Änderungen gemacht werden.

In diesem Zusammenhang gibt es Neuigkeiten: git-lfs im gitlab.rrz aktiviert. Wer also mit der „kleinen“ Lösung zur Versionierung von großen Dateien zufrieden ist, muss sich nur den git-lfs-Client lokal installieren und kann auf das Angebot des RRZ zurückgreifen.

Auch gibt es Neuigkeiten vom RRZ –  der Port 443 (https) wurde weltweit freigeschaltet. Das heißt, man Web-Oberfläche zugreifen und Code clonen,  ohne sich über VPN in das Uni-Netz einzuloggen. Der ssh-Zugriff ist allerdings weiter auf das UHH-Netz beschränkt.