Commit c43bef2c authored by Pape, David (FWCC) - 139658's avatar Pape, David (FWCC) - 139658
Browse files

Updating documentation.

parent 9bf48559
Pipeline #19635 passed with stages
in 6 minutes and 19 seconds
build/
CMakeLists.txt.user
build/
docs/source_code_doc/
from exhale import utils
# show private members aswell; see exhale_args
def specificationsForKind(kind):
'''
For a given input ``kind``, return the list of reStructuredText specifications
for the associated Breathe directive.
'''
# Change the defaults for .. doxygenclass:: and .. doxygenstruct::
if kind == "class" or kind == "struct":
return [
":members:",
":protected-members:",
":private-members:",
":undoc-members:"
]
# Change the defaults for .. doxygenenum::
elif kind == "enum":
return [":no-link:"]
# An empty list signals to Exhale to use the defaults
else:
return []
# -- Project information -----------------------------------------------------
# will be set by CMake
......@@ -9,11 +32,7 @@ release = ''
# -- General configuration ---------------------------------------------------
extensions = [
'recommonmark',
'breathe',
'exhale'
]
extensions = ['recommonmark', 'breathe', 'exhale']
source_suffix = {
'.rst': 'restructuredtext',
......@@ -31,15 +50,13 @@ exhale_args = {
"rootFileTitle": "Source Code Documentation",
"doxygenStripFromPath": "..",
"createTreeView": True,
"exhaleExecutesDoxygen": False
"exhaleExecutesDoxygen": False,
"customSpecificationsMapping": utils.makeCustomSpecificationsMapping(specificationsForKind)
}
primary_domain = 'cpp'
highlight_language = 'cpp'
templates_path = [ '_templates' ]
exclude_patterns = []
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
......@@ -11,8 +11,10 @@ class CICleanupJob : public CIJob {
public:
/**
* @brief Simple constructor.
* @param[in] env The environment provided by GitLab's CI.
*/
CICleanupJob(Environment *env);
/**
* @brief Method used to execute the job.
* @return The exit code of the job.
......
......@@ -11,12 +11,15 @@ class CIConfigJob : public CIJob {
public:
/**
* @brief Simple constructor.
* @param[in] env The environment provided by GitLab's CI.
*/
CIConfigJob(Environment *env);
/**
* @brief Simple destructor.
*/
~CIConfigJob() override = default;
/**
* @brief Method used to execute the job.
* @return The exit code of the job.
......
......@@ -58,14 +58,13 @@ public:
std::string GetVariable(std::string key) override { return Variables[key]; }
private:
int ExitSystemFailure; /**< The exit code to use when the system fails. */
int ExitBuildFailure; /**< The exit code to use when the build fails. */
std::filesystem::path Home; /**< The path to the home directory of the current user. */
std::filesystem::path BuildsDir; /**< The path to the directory where repos are cloned and
builds are executed. */
std::filesystem::path CacheDir; /**< The path to the cache directory. */
std::map<std::string, std::string> Variables; /**< A map containing the environment variables
set by the GitLab runner service. */
int ExitSystemFailure; ///< The exit code to use when the system fails.
int ExitBuildFailure; ///< The exit code to use when the build fails.
std::filesystem::path Home; ///< The path to the home directory of the current user.
std::filesystem::path BuildsDir; ///< The path to the directory where builds are executed.
std::filesystem::path CacheDir; ///< The path to the cache directory.
std::map<std::string, std::string> Variables; /**< Containing the environment variables set by
the GitLab runner service. */
};
#endif // CI_ENVIRONMENT_H
......@@ -22,13 +22,18 @@ public:
/**
* @brief Method that is called to run the job. Children of this class need to implement this.
* @return The exit code of the job.
*/
virtual int Run() = 0;
/**
* @brief Simple getter.
* @return #Env
*/
Environment *GetEnv() { return Env; }
private:
Environment *Env;
Environment *Env; ///< The environment provided by GitLab's CI.
};
#endif // CI_JOB_H
......@@ -16,13 +16,17 @@
class CIJobFactory {
public:
/**
* @brief Simple constructor.
* @param[in] env Sets #Env.
*/
CIJobFactory(Environment *env);
/**
* @brief Creates a \ref CIJob.
* @param[in] jobStage Stage that the \ref CIJob to be created belongs to.
* @param[in] script The path to the script to be executed by the \ref CIJob.
* @param[in] substage Sub-stage that the passed script belongs to.
* @param[in] subStage Sub-stage that the passed script belongs to.
* @param[in] unifiedOutput Defines whether to unify stdout/stderr.
* @return A \ref CIJob matching the given parameters.
*/
......@@ -30,7 +34,7 @@ public:
const std::string &subStage = "", bool unifiedOutput = true);
private:
Environment *Env;
Environment *Env; ///< The environment provided by GitLab's CI.
};
#endif // CI_JOB_FACTORY_H
......@@ -43,8 +43,8 @@ public:
std::string GetSubStage() { return SubStage; }
private:
std::filesystem::path Script; /**< Path to the script to be executed. */
std::string SubStage; /**< The stage of the script. */
std::filesystem::path Script; ///< Path to the script to be executed.
std::string SubStage; ///< The stage of #Script.
};
#endif // JOB_STAGE_H
......@@ -26,21 +26,21 @@ public:
*/
CIRunJobCluster(Environment *env, std::filesystem::path script, std::string subStage,
bool unifiedOutput = true);
/**
* @brief Simple destructor.
*/
~CIRunJobCluster() override = default;
/**
* @brief Method used to execute the job.
* @return The exit code of the job.
*/
int Run() override;
private:
HPCJob *Job; /**< A pointer to the corresponding HPC job for the cluster. */
bool UnifiedOutput; /**< Defines whether stdout and stderr of the HPC jobs are to be unified to
stdout. Unified output is chronologically correct, non-unified output
is outputted to the correct channels (in case GitLab CI will
differentiate between the two in the future). */
HPCJob *Job; ///< A pointer to the corresponding HPC job for the cluster.
bool UnifiedOutput; ///< Defines whether to unify stdout/stderr.
/**
* @brief Helper function, converting std::string.
......@@ -55,7 +55,7 @@ private:
static void Handler(int sig);
static inline CIRunJobCluster *Instance = nullptr; /**< A pointer to an instance of this class
that can be used by #handler to find the
that can be used by #Handler to find the
object. */
};
......
......@@ -18,15 +18,18 @@ public:
/**
* @brief Simple constructor.
* @param[in] script The path to the script to be executed.
* @param[in] substage The stage of the script, e.g. "prepare_script", "get_sources", ...
* @param[in] subStage The stage of the script, e.g. "prepare_script", "get_sources", ...
*/
CIRunJobHead(Environment *env, std::filesystem::path script, std::string subStage);
/**
* @brief Simple destructor.
*/
~CIRunJobHead() override = default;
/**
* @brief Method used to execute the job.
* @return The exit code of the job.
*/
int Run() override;
};
......
......@@ -4,7 +4,9 @@
#include <filesystem>
#include <string>
// Class to make mocking easier.
/**
* @brief Base class to be able to easily mock CIEnvironment.
*/
class Environment {
public:
virtual ~Environment() = default;
......
......@@ -28,6 +28,7 @@ public:
/**
* @brief Method to be used to execute the job.
* @return The exit code of the job.
*/
virtual int Run() = 0;
......@@ -43,7 +44,7 @@ public:
Environment *GetEnv() { return Env; }
private:
Environment *Env;
Environment *Env; ///< The environment provided by the GitLab CI.
};
#endif // HPC_JOB_H
......@@ -24,8 +24,15 @@ public:
*/
SlurmJob(Environment *env, std::filesystem::path script, bool unifiedOutput = true);
/**
* @brief The method to be used to execute the job.
* @return The exit code of the job.
*/
int Run() override;
/**
* @brief The method to be used to cancel the job.
*/
void Cancel() override;
private:
......@@ -67,15 +74,15 @@ private:
*/
std::pair<int, std::string> Execute(const std::string &command);
bool UnifiedOutput; /**< Defines whether to unify stdout and stderr. */
std::map<std::string, std::string> Settings; /**< Contains the specified Slurm options. */
std::filesystem::path Script; /**< The path of the script to be executed. */
std::string ID; /**< The ID of the Slurm job. */
std::string State; /**< The state of the Slurm job: pending, running, canceled, ... */
bool UnifiedOutput; ///< Defines whether to unify stdout and stderr.
std::map<std::string, std::string> Settings; ///< Contains the specified Slurm options.
std::filesystem::path Script; ///< The path of the script to be executed.
std::string ID; ///< The ID of the Slurm job.
std::string State; ///< The state of the Slurm job: pending, running, canceled, ...
std::string ExitCode; /**< The exit code Slurm returns after running #script. In the same
notation as when calling \c scontrol, e.g. "0:0". */
std::filesystem::path OutFile; /**< The path to the output file written by Slurm. */
std::filesystem::path ErrFile; /**< The path to the error file written by Slurm. */
notation as when calling \c scontrol, e.g. "0:0". */
std::filesystem::path OutFile; ///< The path to the output file written by Slurm.
std::filesystem::path ErrFile; ///< The path to the error file written by Slurm.
static std::string YmlToBash(std::string s);
};
......
......@@ -17,6 +17,7 @@ namespace logging {
* read.
* @param[in] home The path to the home directory; ~/logs is used as a fallback when no other
* logging directory is specified.
* @return 0 on success, a non-zero number on failure.
*/
int setup(libconfig::Config &config, std::string home);
}
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment