- Added basic documentation

- Switch from buildpackage.sh to Makefile

Author: dorianim

.github/workflows/build-and-publish-documentation.yml

@@ -0,0 +1,33 @@
+name: build and publish documentation
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          submodules: true  # Fetch Hugo themes (true OR recursive)
+          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
+
+      - name: Setup Sphinx
+        run: |
+          apt update && apt install -y python3-pip build-essential
+          pip install sphinx_rtd_theme
+
+      - name: Build
+        run: |
+          cd docs
+          sphinx-build . ../public/
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: github.ref == 'refs/heads/main'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./public

.github/workflows/release.yml

@@ -17,10 +17,10 @@ jobs:
         uses: actions/checkout@v2
 
       - name: Install dependencies
-        run: sudo apt update && sudo apt install debhelper -y
+        run: sudo apt update && sudo apt install debhelper build-essential -y
 
       - name: Build
-        run: ./buildpackage.sh
+        run: make deb
 
       - name: Copy artifacts
         run: mkdir package && cp ../linuxmuster-linuxclient7_* ./package

.gitignore

@@ -8,3 +8,5 @@ debian/files
 debian/linuxmuster-linuxclient7.debhelper.log
 debian/linuxmuster-linuxclient7.substvars
 debian/linuxmuster-linuxclient7/
+__pycache__
+/public

Makefile

@@ -0,0 +1,16 @@
+.PHONY: help deb docs
+
+help:
+	@echo "Options:"
+	@echo "  deb    Build debian package"
+	@echo "  docs   Build Sphinx documentation"
+	@echo "  clean  Remove built files"
+
+deb:
+	dpkg-buildpackage -rfakeroot -tc -sa -us -uc -I".directory" -I".git" -I"buildpackage.sh"
+
+docs:
+	cd docs && sphinx-build . ../public
+
+clean:
+	rm -r public

buildpackage.sh

@@ -0,0 +1,25 @@
+.wy-nav-side, .wy-side-nav-search, .wy-nav-top  {
+	background-color: #233c4c;
+}
+
+div.rtd-pro.wy-menu, div.rst-pro.wy-menu {
+  display: none;
+}
+
+.wy-side-nav-search > div.version {
+  color: #f49e00;
+  font-size: 1.2em;
+  font-weight: bold;
+}
+
+.wy-menu-vertical p.caption {
+  color: #f49e00;
+}
+
+.wy-menu-vertical a {
+  color: #ffffff
+}
+
+.wy-menu-vertical a:hover {
+  background-color: #f49e00
+}

docs/_static/logo.png

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+import os
+import sys
+import builtins
+
+import sphinx_rtd_theme
+
+sys.path.insert(0, "../usr/lib/python3/dist-packages/")
+
+# Fix gettext syntax
+builtins._ = lambda x:x
+
+extensions = ['sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.autosummary']
+autosummary_generate = True
+
+templates_path = ['_templates']
+source_suffix = '.rst'
+master_doc = 'index'
+
+# General information about the project.
+project = 'linuxmuster-linuxclient7'
+copyright = '2020, Dorian Zedler'
+author = 'Dorian Zedler'
+
+def setup(app):
+    app.add_css_file("theme_overrides.css")
+
+version = "unknown"
+with open("../debian/changelog") as changelogFile:
+    changelog = changelogFile.read()
+    version = changelog.split("\n")[0].split("(")[1].split(")")[0]
+    
+release = version
+
+language = 'en_GB'
+exclude_patterns = []
+pygments_style = 'sphinx'
+todo_include_todos = False
+
+html_theme = 'sphinx_rtd_theme'
+html_logo = '_static/logo.png'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_static_path = ['_static']
+html_sidebars = {
+    '**': [
+        'relations.html',  # needs 'show_related': True theme option to display
+        'searchbox.html',
+    ]
+}
+
+htmlhelp_basename = 'linuxmuster-linuxclient7doc'
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+latex_documents = [
+    (master_doc, 'linuxmuster-7.tex', 'linuxmuster-linuxclient7 Documentation',
+     'Dorian Zedler', 'manual'),
+]
+
+man_pages = [
+    (master_doc, 'linuxmuster-linuxclient7', 'linuxmuster-linuxclient7 Documentation',
+     [author], 1)
+]
+
+
+texinfo_documents = [
+    (master_doc, 'linuxmuster-linuxclient7', 'linuxmuster-linuxclient7 Documentation',
+     author, 'linuxmuster-linuxclient7', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+intersphinx_mapping = {'https://docs.python.org/': None}

docs/_static/theme_overrides.css

@@ -0,0 +1,33 @@
+.. linuxmuster-linuxclient7 documentation 
+
+Linuxmuster-linuxclient7's developer documentation
+==================================================
+
+.. autosummary::
+   :toctree: _autosummary
+   :recursive:
+   :caption: Contents:
+
+About
+-----
+
+Welcome in this API reference documentation !
+
+Linuxmuster-linuxclient7 is a part of the `linuxmuster.net <https://www.linuxmuster.net/de/home/>`_'s project which provides a complete environment for school network management.
+
+You can find the whole description of the install process on the `official documentation page <https://docs.linuxmuster.net/de/latest/>`_ of the project.
+
+In particularly, some `appliances (Proxmox, XCP-ng and KVM) are prepared <https://docs.linuxmuster.net/de/latest/getting-started/installoptions/index.html>`_ in order to permit a fast deployment for test use.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Users
+   :hidden:
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Linuxclient7 Python API
+   :hidden:
+
+   python/shares.rst

docs/conf.py

@@ -0,0 +1,9 @@
+Module: shares
+**************
+
+This is used to deal with mounting and unmounting samba shares.
+
+Shares API
+============
+.. automodule:: linuxmusterLinuxclient7.shares
+   :members:

docs/index.rst

@@ -3,6 +3,20 @@
 from pathlib import Path
 
 def mountShare(networkPath, shareName = None, hiddenShare = False, username = None):
+    """
+    Mount a given path of a samba share
+
+    :param networkPath: Network path of the share
+    :type networkPath: str
+    :param shareName: The name of the share (name of the folder the share is being mounted to)
+    :type shareName: str
+    :param hiddenShare: If the share sould be visible in Nautilus
+    :type hiddenShare: bool
+    :param username: The user in whoms context the share should be mounted
+    :type username: str
+    :return: Tuple: (success, mountpoint)
+    :rtype: tuple
+    """
     networkPath = networkPath.replace("\\", "/")
     username = _getDefaultUsername(username)
     shareName = _getDefaultShareName(networkPath, shareName)
@@ -15,6 +29,23 @@ def mountShare(networkPath, shareName = None, hiddenShare = False, username = No
         return _mountShareWithoutRoot(networkPath, shareName, hiddenShare), mountpoint
 
 def getMountpointOfRemotePath(remoteFilePath, hiddenShare = False, username = None, autoMount = True):
+    """
+    Get the local path of a remote samba share path.
+    This function automatically checks if the shares is already mounted.
+    It optionally automatically mounts the top path of the remote share:
+    If the remote path is `//server/sysvol/linuxmuster.lan/Policies` it mounts `//server/sysvol`
+
+    :param remoteFilePath: Remote path
+    :type remoteFilePath: str
+    :param hiddenShare: If the share sould be visible in Nautilus
+    :type hiddenShare: bool
+    :param username: The user in whoms context the share should be mounted
+    :type username: str
+    :parama autoMount: If the share should be mouted automatically if it is not already mounted
+    :type autoMount: bool
+    :return: Tuple: (success, mountpoint)
+    :rtype: tuple
+    """
     remoteFilePath = remoteFilePath.replace("\\", "/")
     username = _getDefaultUsername(username)
 
@@ -41,6 +72,14 @@ def getMountpointOfRemotePath(remoteFilePath, hiddenShare = False, username = No
     return True, localFilePath
 
 def unmountAllSharesOfUser(username):
+    """
+    Unmount all shares of a given user and safely delete the mountpoints and the parent directory.
+
+    :param username: The username of the user
+    :type username: str
+    :return: True or False
+    :rtype: bool
+    """
     logging.info("=== Trying to unmount all shares of user {0} ===".format(username))
     for basedir in [constants.shareMountBasepath, constants.hiddenShareMountBasepath]:
         shareMountBasedir = basedir.format(username)
@@ -56,7 +95,7 @@ def unmountAllSharesOfUser(username):
 
         if len(os.listdir(shareMountBasedir)) > 0:
             logging.warning("* Mount basedir {} is not empty so not removed!".format(shareMountBasedir))
-            return
+            return False
         else:
             # Delete the directory
             logging.info("Deleting {0}...".format(shareMountBasedir))
@@ -65,10 +104,18 @@ def unmountAllSharesOfUser(username):
             except Exception as e:
                 logging.error("FAILED!")
                 logging.exception(e)
+                return False
 
     logging.info("===> Finished unmounting all shares of user {0} ===".format(username))
+    return True
 
 def getLocalSysvolPath():
+    """
+    Get the local mountpoint of the sysvol
+
+    :return: Full path of the mountpoint
+    :rtype: str
+    """
     rc, networkConfig = config.network()
     if not rc:
         return False, None