Commit 454d66b2 authored by mdolling-gfz's avatar mdolling-gfz Committed by Erxleben, Fredo (FWCC) - 136987
Browse files

Resolve "Create getting started guide"

parent 09822e6e
Pipeline #74680 passed with stages
in 2 minutes and 59 seconds
......@@ -64,8 +64,7 @@ coverage.xml
# Sphinx documentation
docs/_build/
docs/build
docs/source/modules.rst
docs/source/hifis_surveyval.*
docs/source/modules/
# pyenv
.python-version
......
......@@ -26,6 +26,7 @@ comment in file:
- '.*\.yml$'
- '.*\.toml$'
- '.*\.md$'
- '.*\.css$'
- '.*\.gitignore$'
- '.*\.gitmodules$'
- '.*Makefile.*$'
......
......@@ -125,7 +125,7 @@ title = "gitleaks config"
tags = ["key", "API", "generic"]
[rules.allowlist]
paths = ['''scripts''']
regexes = ['''keys\[0\]\+"\["\+codomain_key\+"''', '''key: str = [\"\']G1234[\"\']''', '''KEYWORD_''', '''keys = properties\[''', '''keyring = \[\"keyring\"\]''']
regexes = ['''keys\[0\]\+"\["\+codomain_key\+"''', '''key: str = [\"\']G1234[\"\']''', '''KEYWORD_''', '''keys = properties\[''', '''keyring = \[\"keyring\"\]''','''key_''']
[allowlist]
description = "Allowlisted files"
files = ['''.*gitleaks_config.toml$''', '''(.*?)(jpg|gif|doc|pdf|bin)$''', '''(go.mod|go.sum)$''', '''.*QUALITY.md$''']
<!--
# hifis-surveyval
# Framework to help developing analysis scripts for the HIFIS Software survey.
#
# SPDX-FileCopyrightText: 2021 HIFIS Software <support@hifis.net>
#
# SPDX-License-Identifier: GPL-3.0-or-later
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
hifis-surveyval
Framework to help developing analysis scripts for the HIFIS Software survey.
SPDX-FileCopyrightText: 2021 HIFIS Software <support@hifis.net>
SPDX-License-Identifier: GPL-3.0-or-later
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
-->
# Changelog
......
<!--
# hifis-surveyval
# Framework to help developing analysis scripts for the HIFIS Software survey.
#
# SPDX-FileCopyrightText: 2021 HIFIS Software <support@hifis.net>
#
# SPDX-License-Identifier: GPL-3.0-or-later
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
hifis-surveyval
Framework to help developing analysis scripts for the HIFIS Software survey.
SPDX-FileCopyrightText: 2021 HIFIS Software <support@hifis.net>
SPDX-License-Identifier: GPL-3.0-or-later
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
-->
# Contributing
......
......@@ -38,18 +38,20 @@ coverage: lint
poetry run py.test --cov-report html --cov=$(PROJ_SLUG) tests/
docs: coverage
poetry run sphinx-apidoc -o ./docs/source hifis_surveyval
poetry run sphinx-apidoc -o ./docs/source/modules hifis_surveyval
cd docs && poetry run make html
package: clean docs
poetry build
clean :
rm -rf .pytest_cache \
rm -rf dist \
rm -rf docs/build \
rm -rf *.egg-info \
rm -rf docs/source/modules.rst \
rm -rf docs/source/hifis_surveyval.*
rm -rf docs/source/modules \
rm -rf htmlcov \
rm -rf meta
poetry run coverage erase
reformat:
......
......@@ -325,4 +325,4 @@ This work is licensed under the following license(s):
Please see the individual files for more accurate information.
> **Hint:** We provided the copyright and license information in accordance to the [REUSE Specification 3.0](https://reuse.software/spec/).
> **Hint:** We provided the copyright and license information in accordance to the [REUSE Specification 3.0](https://reuse.software/spec/).
\ No newline at end of file
/*
* hifis-surveyval
* Framework to help developing analysis scripts for the HIFIS Software survey.
*
* SPDX-FileCopyrightText: 2021 HIFIS Software <support@hifis.net>
*
* SPDX-License-Identifier: GPL-3.0-or-later
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
/* use the space we have */
.wy-nav-content {
max-width: none;
}
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Generator: Adobe Illustrator 19.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
viewBox="0 0 318.188 318.188" style="enable-background:new 0 0 318.188 318.188;" xml:space="preserve">
<g>
<polygon style="fill:#E8E8E8;" points="227.321,7.5 40.342,7.5 40.342,310.688 277.846,310.688 277.846,58.025 "/>
<g>
<g>
<path style="fill:#004A94;" d="M158.348,74.91c-15.19,0-25.222,6.307-25.222,12.325v19.196h25.222v2.866h-47.284
c-6.02,0-12.324,10.031-12.324,25.222s6.305,25.222,12.324,25.222h19.193v-11.996c0-8.086,6.578-14.665,14.665-14.665
l26.848-0.002c6.505,0,11.798-5.293,11.798-11.799v-20.738h0.002V87.235C183.569,81.217,173.538,74.91,158.348,74.91z"/>
<circle style="fill:#FFFFFF;" cx="144.679" cy="91.909" r="3.63"/>
</g>
<g>
<path style="fill:#FB9200;" d="M205.632,109.298h-19.198v11.981c0,8.086-6.578,14.664-14.664,14.664l-26.849,0.003
c-6.505,0-11.797,5.293-11.797,11.799v13.234l0.002-0.003v20.827c0,6.019,10.031,12.325,25.222,12.325
s25.222-6.307,25.222-12.325v-19.196h-25.222v-2.866h47.284c6.02,0,12.324-10.031,12.324-25.222S211.651,109.298,205.632,109.298
z"/>
<circle style="fill:#FFFFFF;" cx="172.017" cy="177.13" r="3.63"/>
</g>
</g>
<polygon style="fill:#004A94;" points="235.14,32.763 40.342,32.763 40.342,7.5 227.321,7.5 "/>
<polygon style="fill:#D1D3D3;" points="227.321,58.025 277.846,58.025 227.321,7.5 "/>
<path style="fill:#333E48;" d="M283.149,52.723L232.625,2.197C231.218,0.79,229.311,0,227.321,0H40.342c-4.143,0-7.5,3.358-7.5,7.5
v303.188c0,4.143,3.357,7.5,7.5,7.5h237.504c4.143,0,7.5-3.357,7.5-7.5V58.025C285.346,56.036,284.556,54.129,283.149,52.723z
M234.821,25.606l24.918,24.919h-24.918L234.821,25.606L234.821,25.606z M47.842,15h171.979v10.263H47.842V15z M270.346,303.188
H47.842V40.263h171.979v17.763c0,4.143,3.357,7.5,7.5,7.5h43.024v237.662H270.346z M179.581,251.179l-8.205-17.787h-14.111
l15.785,29.634v18.346h13.062v-18.738l15.785-29.241h-14.046L179.581,251.179z M150.242,237.363
c-3.042-2.647-7.593-3.972-13.652-3.972h-16.606v47.979h12.963v-15.916h3.644c5.819,0,10.31-1.461,13.472-4.382
c3.161-2.921,4.742-7.061,4.742-12.421C154.804,243.773,153.282,240.01,150.242,237.363z M139.954,253.246
c-1.149,1.095-2.697,1.641-4.645,1.641h-2.363v-11.025h3.348c3.588,0,5.383,1.619,5.383,4.856
C141.677,250.643,141.103,252.152,139.954,253.246z"/>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
<g>
</g>
</svg>
hifis-surveyval
Framework to help developing analysis scripts for the HIFIS Software survey.
SPDX-FileCopyrightText: 2021 HIFIS Software <support@hifis.net>
SPDX-License-Identifier: GPL-3.0-or-later
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
\ No newline at end of file
hifis-surveyval
Framework to help developing analysis scripts for the HIFIS Software survey.
SPDX-FileCopyrightText: 2021 HIFIS Software <support@hifis.net>
SPDX-License-Identifier: GPL-3.0-or-later
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
\ No newline at end of file
......@@ -155,6 +155,7 @@ html_theme_options = {}
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["_static"]
html_css_files = ["css/sphinx_rtd_theme.css"]
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
......
.. hifis-surveyval
.. Framework to help developing analysis scripts for the HIFIS Software survey.
..
.. SPDX-FileCopyrightText: 2021 HIFIS Software <support@hifis.net>
..
.. SPDX-License-Identifier: GPL-3.0-or-later
..
.. This program is free software: you can redistribute it and/or modify
.. it under the terms of the GNU General Public License as published by
.. the Free Software Foundation, either version 3 of the License, or
.. (at your option) any later version.
..
.. This program is distributed in the hope that it will be useful,
.. but WITHOUT ANY WARRANTY; without even the implied warranty of
.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.. GNU General Public License for more details.
..
.. You should have received a copy of the GNU General Public License
.. along with this program. If not, see <http://www.gnu.org/licenses/>.
.. _development:
Development
===========
.. toctree::
:maxdepth: 1
:caption: Contents:
development/getting_started
development/make
development/publishing
development/docs
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
\ No newline at end of file
.. hifis-surveyval
.. Framework to help developing analysis scripts for the HIFIS Software survey.
..
.. SPDX-FileCopyrightText: 2021 HIFIS Software <support@hifis.net>
..
.. SPDX-License-Identifier: GPL-3.0-or-later
..
.. This program is free software: you can redistribute it and/or modify
.. it under the terms of the GNU General Public License as published by
.. the Free Software Foundation, either version 3 of the License, or
.. (at your option) any later version.
..
.. This program is distributed in the hope that it will be useful,
.. but WITHOUT ANY WARRANTY; without even the implied warranty of
.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.. GNU General Public License for more details.
..
.. You should have received a copy of the GNU General Public License
.. along with this program. If not, see <http://www.gnu.org/licenses/>.
.. _docs:
.. toctree::
:glob:
**************************
Building the Documentation
**************************
Sphinx
------
The documentation in this project is generated by
`Sphinx <http://www.sphinx-doc.org/en/master/>`_
from `reStructuredTex <http://docutils.sourceforge.net/rst.html>`_.
Ubuntu/Debian
-------------
This project started on `Ubuntu Linux 18.04 <http://releases.ubuntu.com/18.04/>`_.
That doesn't mean you can't use another distribution, or even another operating
system, but you may need to perform some additional setup steps to get your
builds working. (If you do get it working under another system, please consider
adding an article to let others know how you did it!)
Prerequisites
^^^^^^^^^^^^^
The project uses the Sphinx
`LatexBuilder <http://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.latex.LaTeXBuilder>`_
to generate a `PDF <https://acrobat.adobe.com/us/en/acrobat/about-adobe-pdf.html>`_
document. If you're using Ubuntu (or Debian) you'll need to install
`texlive <https://www.tug.org/texlive/>`_ and
`latexmk <https://mg.readthedocs.io/latexmk.html>`_.
.. code-block:: bash
sudo apt-get install texlive-latex-recommended \
texlive-latex-extra \
texlive-fonts-recommended \
latexmk
make
----
Once everything is in place, you can build the documentation using the
:ref:`make docs <make_docs>` the target defined in the project's
:ref:`Makefile <make>`.
.. code-block::
make docs
\ No newline at end of file
.. hifis-surveyval
.. Framework to help developing analysis scripts for the HIFIS Software survey.
..
.. SPDX-FileCopyrightText: 2021 HIFIS Software <support@hifis.net>
..
.. SPDX-License-Identifier: GPL-3.0-or-later
..
.. This program is free software: you can redistribute it and/or modify
.. it under the terms of the GNU General Public License as published by
.. the Free Software Foundation, either version 3 of the License, or
.. (at your option) any later version.
..
.. This program is distributed in the hope that it will be useful,
.. but WITHOUT ANY WARRANTY; without even the implied warranty of
.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.. GNU General Public License for more details.
..
.. You should have received a copy of the GNU General Public License
.. along with this program. If not, see <http://www.gnu.org/licenses/>.
.. _getting_started_dev:
.. toctree::
:glob:
***************
Getting Started
***************
This section provides instructions for setting up your development environment. If you follow the
steps from top to bottom you should be ready to roll by the end.
Get the Source
==============
The source code for the `SurveyAnalysis2020` project lives at
`Gitlab <https://gitlab.hzdr.de/hifis/survey-analysis-2020>`_.
You can use `git clone` to get it.
.. code-block:: bash
git clone https://gitlab.hzdr.de/hifis/survey-analysis-2020
Create the Virtual Environment
==============================
You can create a virtual environment and install the project's dependencies using :ref:`make <make>`.
.. code-block:: bash
make venv
make install
source venv/bin/activate
Try It Out
==========
One way to test out the environment is to run the tests. You can do this with the `make test`
target.
.. code-block:: bash
make test
If the tests run and pass, you're ready to roll.
Getting Answers
===============
Once the environment is set up, you can perform a quick build of this project
documentation using the `make answers` target.
.. code-block:: bash
make answers
.. hifis-surveyval
.. Framework to help developing analysis scripts for the HIFIS Software survey.
..
.. SPDX-FileCopyrightText: 2021 HIFIS Software <support@hifis.net>
..
.. SPDX-License-Identifier: GPL-3.0-or-later
..
.. This program is free software: you can redistribute it and/or modify
.. it under the terms of the GNU General Public License as published by
.. the Free Software Foundation, either version 3 of the License, or
.. (at your option) any later version.
..
.. This program is distributed in the hope that it will be useful,
.. but WITHOUT ANY WARRANTY; without even the implied warranty of
.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.. GNU General Public License for more details.
..
.. You should have received a copy of the GNU General Public License
.. along with this program. If not, see <http://www.gnu.org/licenses/>.
.. _publishing:
**********************
Publishing the Package
**********************
As you make changes to the project, you'll probably want to publish new version
of the package. *(That's the point, right?)*
Publishing
==========
The actual process of publishing the project is just a matter of running the
:ref:`publish <make-publish>` target.
.. code-block:: bash
make publish
Installing
==========
If you just need to install the library in your project, have a look at
the :ref:`general tutorial <getting_started>` article.
.. hifis-surveyval
.. Framework to help developing analysis scripts for the HIFIS Software survey.
..
.. SPDX-FileCopyrightText: 2021 HIFIS Software <support@hifis.net>
..
.. SPDX-License-Identifier: GPL-3.0-or-later
..
.. This program is free software: you can redistribute it and/or modify
.. it under the terms of the GNU General Public License as published by
.. the Free Software Foundation, either version 3 of the License, or
.. (at your option) any later version.
..
.. This program is distributed in the hope that it will be useful,
.. but WITHOUT ANY WARRANTY; without even the implied warranty of
.. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.. GNU General Public License for more details.
..
.. You should have received a copy of the GNU General Public License
.. along with this program. If not, see <http://www.gnu.org/licenses/>.
.. _getting_started:
.. toctree::
:glob:
***************
Getting Started
***************
Installing the Library
======================
You can use pip to install `hifis_surveyval`.
.. code-block:: sh
pip install hifis_surveyval
Interface Documentation
=======================
.. click:: hifis_surveyval.cli:cli
:prog: hifis_surveyval
:nested: full
......@@ -27,16 +27,23 @@ SurveyAnalysis2020
This project is used to develop analysis scripts for the HIFIS Software survey.
There are two scopes of developers within this project.
The first one is ``analysis script developer``, which are using
hifis-surveyval to analyse data sets. Please see the `Getting Started
<./pages/getting_started>`_ guide.
The other one is ``hifis-surveyval developer``, which are changing
hifis-surveyval itself. Please see the `Developer Guide
<./pages/development>`_.
.. toctree::
:maxdepth: 2
:caption: Contents:
getting_started
api
development
requirements
pages/getting_started
pages/development
pages/api
Indices and tables
==================
......
......@@ -18,15 +18,20 @@
.. You should have received a copy of the GNU General Public License
.. along with this program. If not, see <http://www.gnu.org/licenses/>.
.. _api:
.. toctree::
:glob:
API Documentation
=================
CLI Interface
-------------
.. click:: hifis_surveyval.cli:cli
:prog: hifis_surveyval
:nested: full
Modules
-------
.. toctree::