cepgen is hosted by Hepforge, IPPP Durham
CepGen 1.2.5
Central exclusive processes event generator
Loading...
Searching...
No Matches
DocumentationGenerator.cpp
Go to the documentation of this file.
1/*
2 * CepGen: a central exclusive processes event generator
3 * Copyright (C) 2022-2024 Laurent Forthomme
4 *
5 * This program is free software: you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation, either version 3 of the License, or
8 * any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program. If not, see <http://www.gnu.org/licenses/>.
17 */
18
19#include <CTML/ctml.hpp>
20#include <fstream>
21#include <iostream>
22
23#include "CepGen/Core/Exception.h"
24#include "CepGen/Modules/DocumentationGeneratorFactory.h"
25#include "CepGen/Utils/DocumentationGenerator.h"
26#include "CepGen/Utils/String.h"
27#include "CepGen/Version.h"
28
29namespace cepgen {
30 namespace ctml {
34 class DocumentationGenerator final : public cepgen::utils::DocumentationGenerator {
35 public:
36 inline explicit DocumentationGenerator(const ParametersList& params)
37 : cepgen::utils::DocumentationGenerator(params),
38 bare_(steer<bool>("bare")),
39 container_(CTML::Node("div.container-fluid")) {}
40
41 inline static ParametersDescription description() {
42 auto desc = cepgen::utils::DocumentationGenerator::description();
43 desc.setDescription("CTML HTML document generator helper");
44 desc.add<std::string>("output", "index.html").setDescription("output path for the generated HTML file");
45 desc.add<std::string>("pageTitle", "Modules documentation")
46 .setDescription("documentation page upper level title");
47 desc.add<bool>("useBS", true).setDescription("use the Bootstrap CDN to prettify this output?");
48 desc.add<bool>("showGit", false).setDescription("print out the git hash/branch in the output?");
49 desc.add<bool>("bare", false)
50 .setDescription("generate a bare version (without <html>/<head>/<body> attributes)");
51 return desc;
52 }
53
54 inline std::string describe() override {
55 doc_.AppendNodeToHead(CTML::Node("title", "CepGen v" + version::tag + " modules documentation"));
56 if (!bare_ && steer<bool>("useBS")) {
57 doc_.AppendNodeToHead(
58 CTML::Node("link")
59 .SetAttribute("rel", "stylesheet")
60 .SetAttribute("href", "https://cdn.jsdelivr.net/npm/bootstrap@4.3.1/dist/css/bootstrap.min.css")
61 .SetAttribute("integrity", "sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T")
62 .SetAttribute("crossorigin", "anonymous"));
63 doc_.AppendNodeToHead(CTML::Node("meta")
64 .SetAttribute("name", "viewport")
65 .SetAttribute("content", "width=device-width, initial-scale=1"));
66 }
67 if (const auto page_title = steer<std::string>("pageTitle"); !page_title.empty())
68 container_.AppendChild(CTML::Node("h1", page_title));
69 auto header = CTML::Node("div").AppendText("CepGen version ").AppendChild(CTML::Node("mark", version::tag));
70 if (steer<bool>("showGit"))
71 header.AppendChild(CTML::Node("br").UseClosingTag(false))
72 .AppendText("Git hash/branch: ")
73 .AppendChild(CTML::Node("code", version::extended));
74 header.AppendChild(CTML::Node("br").UseClosingTag(false))
75 .AppendText("Documentation last generated on " + utils::timeAs("%B %d, %Y"));
76 container_.AppendChild(header);
77 for (const auto& cat : categories_) {
78 container_.AppendChild(CTML::Node("a")
79 .SetAttribute("name", cat.first)
80 .AppendChild(CTML::Node("h2", cat.second.title).SetAttribute("id", cat.first)));
81 CTML::Node mods("p");
82 for (const auto& mod : cat.second.modules)
83 mods.AppendChild(CTML::Node("a")
84 .SetAttribute("name", utils::toString(cat.first) + mod.first)
85 .AppendChild(CTML::Node("span").AppendChild(
86 moduleDescription(mod.second,
87 cat.second.modules_indices.count(mod.first) > 0
88 ? cat.second.modules_indices.at(mod.first)
89 : -1)
90 .SetAttribute("id", cat.first + mod.first))));
91 container_.AppendChild(mods);
92 }
93 doc_.AppendNodeToBody(container_);
94 std::ostringstream out;
95 if (bare_)
96 out << container_.ToString();
97 else
98 out << doc_.ToString();
99 return out.str();
100 }
101
102 private:
103 inline static CTML::Node moduleDescription(const ParametersDescription& desc, int index = -1) {
104 CTML::Node out("div.module");
105 if (desc.empty())
106 return out;
107 CTML::Node node_summary("summary");
108 node_summary.AppendChild(CTML::Node("b", desc.parameters().getNameString()));
109 if (index > 0)
110 node_summary.AppendText(" (index ").AppendChild(CTML::Node("code", std::to_string(index))).AppendText(")");
111 CTML::Node mod_summary(node_summary);
112 CTML::Node mod_details("details");
113 CTML::Node mod_params_list(CTML::Node("p").AppendText("List of parameters:"));
114 const auto desc_type = desc.type();
115 if (desc_type == ParametersDescription::Type::ParametersVector)
116 mod_summary.AppendChild(CTML::Node("b", "Children attributes"));
117 else if (desc_type == ParametersDescription::Type::Parameters)
118 mod_summary.AppendChild(CTML::Node("b", "parameters list"));
119 else if (desc_type == ParametersDescription::Type::Value) {
120 } else {
121 mod_summary.AppendText(" " + desc.description());
122 }
123 mod_details.AppendChild(mod_summary);
124 try {
125 CTML::Node items("ul");
126 for (const auto& key : desc.parameters().keys(false)) {
127 const auto& subdesc = desc.get(key);
128 const auto subdesc_type = subdesc.type();
129 CTML::Node item("li.key");
130 item.AppendChild(CTML::Node("u.key", key));
131 if (subdesc_type == ParametersDescription::Type::Value) {
132 if (!subdesc.description().empty())
133 item.AppendChild(CTML::Node("i", " " + subdesc.description()));
134 if (!desc.parameters().getString(key).empty())
135 item.AppendText(" ").AppendChild(
136 CTML::Node("span.text-muted")
137 .AppendText("(default value: ")
138 .AppendChild(CTML::Node("code", desc.parameters().getString(key, false)))
139 .AppendText(")"));
140 if (const auto& allowed_vals = desc.get(key).allowedValues(); !allowed_vals.empty()) {
141 item.AppendText(". Allowed values:");
142 CTML::Node itparams("ul");
143 for (const auto& it : allowed_vals.allowed()) {
144 CTML::Node val("li");
145 val.AppendChild(CTML::Node("code", it.first));
146 if (!it.second.empty())
147 val.AppendText(" (" + it.second + ")");
148 itparams.AppendChild(val);
149 }
150 item.AppendChild(itparams);
151 }
152 } else if (subdesc_type == ParametersDescription::Type::ParametersVector) {
153 item.AppendText(" vector of parameters");
154 if (!subdesc.description().empty())
155 item.AppendText(" defining a ").AppendChild(CTML::Node("i", subdesc.description()));
156 item.AppendChild(moduleDescription(subdesc));
157 if (const auto& vparams = desc.parameters().get<std::vector<ParametersList> >(key); !vparams.empty()) {
158 CTML::Node itparams("ol");
159 for (const auto& it : vparams)
160 itparams.AppendChild(CTML::Node("li").AppendChild(moduleDescription(ParametersDescription(it))));
161 item.AppendChild(
162 CTML::Node("details")
163 .AppendChild(CTML::Node("summary").AppendChild(CTML::Node("b", "Default vector content")))
164 .AppendChild(CTML::Node("p").AppendChild(itparams.SetAttribute("start", "0"))));
165 }
166 } else
167 item.AppendChild(CTML::Node("i", " " + subdesc.description())).AppendChild(moduleDescription(subdesc));
168 items.AppendChild(item);
169 }
170 if (!items.GetChildren().empty()) {
171 if (desc_type == ParametersDescription::Type::ParametersVector ||
172 desc_type == ParametersDescription::Type::Parameters)
173 mod_details.AppendChild(items);
174 else
175 mod_details.AppendChild(mod_params_list.AppendChild(items));
176 }
177 out.AppendChild(mod_details);
178 } catch (const Exception& exc) {
179 exc.dump();
180 }
181 return out;
182 }
183
184 const bool bare_;
185 CTML::Document doc_;
186 CTML::Node container_;
187 };
188 } // namespace ctml
189} // namespace cepgen
190using DocumentationGeneratorCTML = cepgen::ctml::DocumentationGenerator;
191REGISTER_DOCUMENTATION_GENERATOR("ctml", DocumentationGeneratorCTML);
REGISTER_DOCUMENTATION_GENERATOR
#define REGISTER_DOCUMENTATION_GENERATOR(name, obj)
Add a documentation generator to the list of handled modules.
Definition DocumentationGeneratorFactory.h:25
cepgen::ParametersDescription
A description object for parameters collection.
Definition ParametersDescription.h:26
cepgen::ParametersDescription::parameters
ParametersList & parameters()
List of parameters associated to this description object.
Definition ParametersDescription.cpp:216
cepgen::ParametersDescription::empty
bool empty() const
Does a description of this parameter (or parameters collection) exist?
Definition ParametersDescription.cpp:48
cepgen::ParametersDescription::allowedValues
const ParameterValues & allowedValues() const
Possible values for a parameter.
Definition ParametersDescription.h:116
cepgen::ParametersDescription::type
Type type() const
Get the type of parameter considered.
Definition ParametersDescription.cpp:86
cepgen::ParametersDescription::description
const std::string & description() const
Description of this parameter (or parameters collection)
Definition ParametersDescription.h:51
cepgen::ParametersDescription::get
const ParametersDescription & get(const std::string &) const
Get the description of a sub-object.
Definition ParametersDescription.cpp:74
cepgen::ParametersList::get
T get(const std::string &key, const T &def=default_arg< T >::get()) const
Get a parameter value.
Definition ParametersList.cpp:391
cepgen::ParametersList::getNameString
std::string getNameString(bool wrap=false) const
Get a string-converted version of the module name if any.
Definition ParametersList.h:142
cepgen::ParametersList::getString
std::string getString(const std::string &key, bool wrap=false) const
Get a string-converted version of a value.
Definition ParametersList.cpp:313
cepgen::Steerable::steer
T steer(const std::string &key) const
Retrieve a parameters as previously steered.
Definition Steerable.h:39
cepgen::SteeredObject::parameters
const ParametersList & parameters() const override
Module user-defined parameters.
Definition SteeredObject.h:54
cepgen::ctml::DocumentationGenerator
CTML documentation generator object.
Definition DocumentationGenerator.cpp:34
cepgen::ctml::DocumentationGenerator::DocumentationGenerator
DocumentationGenerator(const ParametersList &params)
Definition DocumentationGenerator.cpp:36
cepgen::ctml::DocumentationGenerator::description
static ParametersDescription description()
Definition DocumentationGenerator.cpp:41
cepgen::utils::DocumentationGenerator::description
static ParametersDescription description()
Definition DocumentationGenerator.cpp:90
cepgen::utils::DocumentationGenerator::categories_
std::vector< std::pair< std::string, category_t > > categories_
Definition DocumentationGenerator.h:44
cepgen::utils::timeAs
std::string timeAs(const std::string &fmt)
Return the formatted date/time now.
Definition String.cpp:110
cepgen::utils::toString
std::string toString(const std::wstring &str)
Convert a wide characters to a standard characters string.
Definition String.cpp:151
cepgen
Common namespace for this Monte Carlo generator.
Definition CommandLineHandler.cpp:36
cepgen::version::tag
static const std::string tag
CepGen version.
Definition Version.h:28
cepgen::version::extended
static const std::string extended
CepGen detailed version.
Definition Version.h:30