create documentation basics

This patch creates the basics for documentation.

Signed-off-by: Amy Parker <amy@amyip.net>

.gitignore

@@ -12,4 +12,7 @@ ssvp-config*.json
 *.js
 *.db
 target/
-*.pem
+*.pem
+_build/
+_static/
+_templates/

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,28 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'SSVP'
+copyright = '2023, Amy Parker'
+author = 'Amy Parker'
+release = 'v0.2.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["sphinx_rtd_theme"]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

docs/configuration.rst

@@ -0,0 +1,42 @@
+Configuration
+=============
+
+Here's all of the configuration options:
+
+- :code:`enable_host_ipv6`: Determines whether to enable IPv6 support. On non-Linux OSes, having this option enabled may disable IPv4 support. (optional)
+    - Allowed values: :code:`true`, :code:`false`
+- :code:`ssl`: Determines SSL support, and configuration settings.
+    - Allowed values:
+        - :code:`null`: disables SSL
+        - :code:`["/path/to/cert.pem", "/path/to/key.pem"]`: uses existing certificates/keyfiles
+        - :code:`"adhoc"`: Uses self-signed/ad-hoc certificates
+- :code:`port`: Port number for the SSVP server (optional)
+    - Allowed values: any integer from 1 to 65535 (note: 1-1024 require root/sudo)
+- :code:`instance_name`: Name put in the navbar brand for the instance
+    - Allowed values: any string
+- :code:`splash`: Splash text for the main page (optional)
+    - Allowed values: any string
+- :code:`servers`: List of servers, set as an object
+    - Allowed values: must fit the following schema:
+        .. code-block:: json
+            
+            "name_of_server": {
+                "ip": "ip address (url for http)",
+                "module": "testing module name",
+                "args": "list of module arguments"
+            }
+            
+- :code:`services`: List of services, set as an object
+    - Allowed values: must fit the servers schema
+- :code:`database`: Database information
+    - Note: the only options required on sqlite3 are :code:`host`, :code:`type`, and :code:`prefix`
+    - :code:`type`: database type
+        - Either :code:`mysql`, :code:`postgres`, :code:`sqlite3`
+    - :code:`host`: database host IP/sqlite3 file path
+        - Valid IPv4 or IPv6 address
+    - :code:`port`: database port
+        - Valid TCP port (unix sockets are not supported)
+    - :code:`username`: database username
+    - :code:`password`: database password
+    - :code:`database`: name of database in the DB system
+    - :code:`prefix`: prefix for tables

docs/contributing.rst

@@ -0,0 +1,98 @@
+Contributing
+============
+
+Thanks for wanting to help with the development of SSVP! Here's how you can contribute.
+
+Ways to Contribute
+------------------
+
+- **Submit bug reports**: when you find a problem in SSVP, report it `here <https://github.com/amyipdev/ssvp/issues>`_.
+- **Write code**: See below on how to write code and submit it to SSVP.
+- **Contribute to documentation**: Similar procedures to writing code, but work is done in the :code:`docs/` folder.
+- **Translation**: We don't have internationalization set up yet, but if you'd like to assist, `let us know <mailto:amy@amyip.net>`_.
+
+Getting Started
+---------------
+
+The first thing you need to do is to create a fork of the project. You need a GitHub account for this; if you don't want to make one, reach out to us.
+
+To create a fork, go to the `SSVP project page <https://github.com/amyipdev/ssvp>`_, and click the Fork button:
+
+.. image:: _images/fork.png
+
+You then need to download your fork to your local machine (make sure you have git installed):
+
+.. code-block:: bash
+
+    git clone --depth=1 https://github.com/yourGitHubUsername/ssvp
+    
+You then want to run the `installation process <installing.html>`_. This will help you get all your dependencies installed.
+If you're just doing development work, you probably won't have a database already set up yet. As a result, we recommend using a local `sqlite3` installation
+when setting up the database functionality. When choosing an installation directory, keep it as the default option. Don't set an "autorunner" or "server reboot launch method".
+
+Creating a Patch
+----------------
+
+Now that you're all set up, it's time to create a patch.
+
+First, you need to establish a branch for your patch. It should be given a relevant name; for instance, if you're implementing Windows support for the interval module, a possible branch name could be `interval-windows-support`.
+
+Once you've chosen the name, create and switch to the branch:
+
+.. code-block:: bash
+
+    git checkout -b your-branch-name
+    
+You can now freely modify files, building your patch. When you're ready to save an interval of your progress, run:
+
+.. code-block:: bash
+
+    git add -A
+    git commit
+    
+Saving an interval doesn't automatically push all the changes. All of the "commits" will be sent when you propose the changes.
+
+Running the commit command opens up a dialog asking you to put a message for the commit. This should be of the form:
+
+.. code-block::
+
+    active subject line
+    
+    This patch (say what the patch does). (Justify why it should be added).
+    
+    Signed-off-by: Your Name <email@address.tld>
+    
+The subject line should be stated as an action; instead of "changes x to y", it should be "change x to y".
+
+If your commit is resolving a bug, add another line, where XX is the issue number:
+
+.. code-block::
+
+    Fixes: #XX
+    
+When you're done creating commits, run the following command:
+
+.. code-block::
+
+    git push --set-upstream origin (name of your branch)
+    
+Then, go to your fork on GitHub. As long as you do this step shortly after you push, it should say something about your branch having "recent changes". Click the button to submit a pull request.
+If there is no button there, go to pull requests, and open one manually.
+
+The source branch should be set as your new branch. The target branch should be set as amyipdev/main. You can then write a title and description for your PR. It should
+follow the same format as the commit message format, with the subject line becoming the title.
+
+When you're ready, you can click the "create pull request" button. This will send it off.
+
+Reviewing
+---------
+
+Someone will come along to review your patch. They may have suggestions and/or comments on it; these should be addressed when you are able.
+You may need to add additional comments to fix issues presented by reviewers.
+
+When ready, the PR will be accepted. That means your code has made it into SSVP.
+
+Resetting Your Fork
+-------------------
+
+When you make your next patch, before branching, you should sync your fork. This can be done with the "Sync" button on GitHub when you're viewing your main branch.

docs/index.rst

@@ -0,0 +1,28 @@
+.. SSVP documentation master file, created by
+   sphinx-quickstart on Mon Aug  7 09:58:30 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+SSVP: The Server Statistics Viewer Project
+==========================================
+
+SSVP is a utility for viewing statistics and information about your servers, services, and more. It's designed to be a public front page for uptime information,
+helping your users know whether issues are coming from your side or theirs.
+
+If you're looking to help build the future of SSVP, go to the `contributor's guide <contributing.html>`_.
+If you're just trying to get SSVP set up, go to the `installation guide <installing.html>`_.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   contributing
+   installing
+   configuration
+
+
+
+Utilities
+---------
+- Index: :ref:`genindex`
+- Search: :ref:`search`

docs/installing.rst

@@ -0,0 +1,73 @@
+Installation
+============
+
+Installation of SSVP is usually simple, thanks to the easy installer (:code:`./install.sh`).
+
+Supported Operating Systems
+---------------------------
+
+Right now, we're currently focusing on just supporting Linux. \*BSD and macOS support may come in the future; Windows support is unlikely.
+
+Theoretically, any Linux distribution should work. We currently only officially support **Debian 12** and **Fedora 38**.
+
+Our dependency installer currently has support for most **apt**-based and **dnf/yum**-based distributions. Support for other package managers is a `planned feature <https://github.com/amyipdev/ssvp/issues/23>`_.
+The dependency verifier works on all systems, **but cannot check the presence of libpq and its headers**.
+
+If you have to install dependencies manually, be aware that you need all of the packages list `here <https://github.com/amyipdev/ssvp/blob/main/installer/autoinstall-deps-system.sh>`_.
+
+Downloading SSVP
+----------------
+
+You need Git in order to download SSVP.
+
+Once Git is installed, run:
+
+.. code-block:: bash
+
+    git clone --depth=1 https://github.com/amyipdev/ssvp
+
+Running the Installation Script
+-------------------------------
+
+To run the installation script, from the SSVP download directory, run:
+
+.. code-block:: bash
+
+    ./install.sh
+    
+Installation Components
+-----------------------
+
+The installer will prompt you on whether to run several of its modules. Defaults are always in brackets, such as :code:`not default/[default]`.
+
+The first option is to autoinstall system dependencies. You should only respond yes if you are on a **Fedora** or **Debian** derivative system. This includes:
+
+- `Red Hat Enterprise Linux <https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux>`_
+- `Fedora Linux <https://fedoraproject.org/>`_
+- `Debian Linux <https://www.debian.org/>`_
+- `Ubuntu Linux <https://ubuntu.com/>`_ (and its derivatives, such as `Kubuntu <https://kubuntu.org/>`_ and `Linux Mint <https://linuxmint.com/>`_)
+- `CentOS Linux <https://centos.org/>`_, `Rocky Linux <https://rockylinux.org/>`_, and `Alma Linux <https://almalinux.org/>`_
+
+If you decline the option, you'll be given the choice to verify your system dependencies. This just checks that they're all available in the PATH, and works on any system.
+
+If you don't have a virtual environment already, you'll be asked if you want one created. This is highly recommended, and on many systems, it is extremely difficult not to use one.
+If one exists or you opted to create one, you'll be asked if you want to source the venv. This is mandatory for it to work properly.
+
+You'll then be asked about installing other types of dependencies. The PyPI option installs dependencies from :code:`requirements.txt`. If you have no intention of using or testing postgres,
+you may be able to get away with not installing `psycopg2`; it takes a while to compile on lower-powered systems and takes up a decent amount of space, so skipping it may be of interest.
+All of the node dependencies are required for building SSVP; as such, you should generally opt to autoinstall the NPM dependencies. The last option is site dependencies; this just runs
+:code:`make` prior to setting everything else up. If you're planning on running `make` for some purpose later anyways, this is unnecessary.
+
+You'll then be asked to work with the database and with the SSVP configuration. You can always configure things later, but the config file script greatly helps with initial setup.
+The database step presumes you have an existing database, or that you're going to be using `sqlite3`. You'll need database credentials on hand when running the initialization.
+If you use the defaults for databases, you should use the defaults in the config file database section. Initializing cached statistics is also highly recommended, as SSVP will
+fail to run without the entries.
+
+The full installation is meant for server installs, when you want to segregate the installations and have automation set up for you automatically. If you're a developer,
+this often is not necessary. Cron is currently the only supported mode for autoinstallation; please note your cron setup needs to be able to support `@reboot` (most do, but some old editions don't).
+Systemd (and OpenRC) support will be added eventually.
+
+You're now done with the installation. You can run the server by running `srv/tmux.sh`. It should print :code:`no current client` when done. You can check on the server by running `tmux attach`,
+and disconnect from it by pressing `CTRL-b d`.
+
+If you need to change settings in your configuration file, please see the `configuration guide <configuration.html>`_.

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

install.sh

@@ -112,12 +112,12 @@ fi
 
 echo -n "Installation directory [current directory]: "
 read INSDIR
-if [ "$INSDIR" == "" ]; then
-    INSDIR=$(pwd)
+if [ "$INSDIR" != "" ]; then
+    $PREROOT make install INSTALLDIR=$INSDIR
+else
+    INSDIR="$(pwd)"
 fi
 
-$PREROOT make install INSTALLDIR=$INSDIR
-
 echo -n "Choose an autorunner method (cron/[none]): "
 read ATRMTH
 if [ "$ATRMTH" == "cron" ]; then
@@ -131,7 +131,7 @@ if [ "$RBTLNC" == "cron" ]; then
     (crontab -l; echo "@reboot $INSDIR/srv/tmux.sh") | crontab -
 fi
 
-echo "Installation finished. Remember to set up a cron job for srv/interval.py to run every 5 minutes (this will be automated in the future)"
+echo "Installation finished."
 
 # next todo: cron (also implement systemd timers)
 # next todo: systemd service for web server?

requirements.txt

@@ -4,4 +4,6 @@ ping3
 requests
 psycopg2
 pyopenssl
-gunicorn
+gunicorn
+sphinx
+sphinx_rtd_theme