-
Notifications
You must be signed in to change notification settings - Fork 2
/
websiteAndDocumentation.html
241 lines (221 loc) · 14.4 KB
/
websiteAndDocumentation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Website and Documentation — VOTCA 2024.2-dev documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/css/custom.css" type="text/css" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script src="_static/documentation_options.js?v=76c55136"></script>
<script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script crossorigin="anonymous" integrity="sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="prev" title="Code of Conduct" href="CODE_OF_CONDUCT.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html">
<img src="_static/customLogo.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul>
<li class="toctree-l1"><a class="reference internal" href="INSTALL.html">Installation</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Manuals</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="tools/index.html">TOOLS Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="csg/index.html">CSG Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="xtp/XTP-MANUAL.html">XTP Manual</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Tutorials</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="csg-tutorials/Tutorial.html">CSG Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="xtp-tutorials/XTP-TUTORIAL.html">XTP Tutorials</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Development</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="DEVELOPERS_GUIDE.html">Developer and Contributor Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="VOTCA_LANGUAGE_GUIDE.html">VOTCA Internal Contributor Language Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="Architecture.html">The architecture of VOTCA</a></li>
<li class="toctree-l1"><a class="reference internal" href="xtp/Architecture.html">Architecture of votca-xtp</a></li>
<li class="toctree-l1"><a class="reference internal" href="CODE_OF_CONDUCT.html">Code of Conduct</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Website and Documentation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#building-the-documentation-and-website-locally">Building the documentation and website locally</a></li>
<li class="toctree-l2"><a class="reference internal" href="#rebuilding-the-website-after-changes">Rebuilding the website after changes</a></li>
<li class="toctree-l2"><a class="reference internal" href="#editing-existing-pages">Editing existing pages</a></li>
<li class="toctree-l2"><a class="reference internal" href="#writing-a-new-page">Writing a new page</a></li>
<li class="toctree-l2"><a class="reference internal" href="#changing-the-theme">Changing the theme</a></li>
<li class="toctree-l2"><a class="reference internal" href="#publishing-your-changes">Publishing your changes</a></li>
<li class="toctree-l2"><a class="reference internal" href="#more-advanced-stuff">More Advanced Stuff</a></li>
</ul>
</li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Community</span></p>
<ul>
<li class="toctree-l1"><a class="reference external" href="https://github.com/votca">GitHub</a></li>
<li class="toctree-l1"><a class="reference external" href="https://twitter.com/votca_software">Twitter</a></li>
<li class="toctree-l1"><a class="reference external" href="https://groups.google.com/g/votca">Forum</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">VOTCA</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Website and Documentation</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/websiteAndDocumentation.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="website-and-documentation">
<h1>Website and Documentation<a class="headerlink" href="#website-and-documentation" title="Link to this heading">¶</a></h1>
<p>On this page you will find all the information you need to contribute to VOTCA’s
website and documentation.</p>
<p>The website is build with Sphinx and uses a slightly modified version of the
Read the Docs theme. Parts of the documentation is automatically generated
based on the source code of VOTCA and jupyter notebooks, other parts are written
by hand. The markup language of Sphinx is reStructuredText, think of it as
Markdown on steroids.</p>
<p>To start working on the website and documentation you will first need to be able
to build it, this is discussed first. Next, a brief overview of how to edit
existing pages and adding new ones is given. Finally, we discuss how to change the theme and publish the changes.</p>
<section id="building-the-documentation-and-website-locally">
<h2>Building the documentation and website locally<a class="headerlink" href="#building-the-documentation-and-website-locally" title="Link to this heading">¶</a></h2>
<p>To be able to see and test changes you make to the website, you will need to
build it locally. You will first need to install and build VOTCA. Once you have
installed VOTCA, navigate to its build folder (if you followed the install
instructions, it will be called <code class="docutils literal notranslate"><span class="pre">builddir</span></code>). In the build folder, run</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>sphinx
</pre></div>
</div>
<p>This will probably output errors on the first few tries, read them carefully
since they will almost always be missing python packages. Find which
package/module is missing in the error message and simply install it with <code class="docutils literal notranslate"><span class="pre">pip3</span>
<span class="pre">install</span> <span class="pre"><packagename></span></code>.</p>
<p>A short list of packages you probably need to install manually:</p>
<ul class="simple">
<li><p>cma</p></li>
<li><p>recommonmark</p></li>
<li><p>nbsphinx</p></li>
<li><p>sphinx_rtd_theme</p></li>
</ul>
<p>Once the errors are gone, the documentation is build and a static html website is
generated in the <code class="docutils literal notranslate"><span class="pre">sphinx.html</span></code> folder within the build folder. You can view
and test the website in any browser simply by navigating to the index.html file
within the <code class="docutils literal notranslate"><span class="pre">sphinx.html</span></code> folder.</p>
</section>
<section id="rebuilding-the-website-after-changes">
<h2>Rebuilding the website after changes<a class="headerlink" href="#rebuilding-the-website-after-changes" title="Link to this heading">¶</a></h2>
<p>After you updated files you will need to rebuild the website to see your changes.</p>
<p>If you simply changed the contents of a .rst file you can rerun <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">sphinx</span></code> to propagate the changes. If you refresh the browser, the changes will have taken
effect.</p>
<p>If you, however, changed the theme or added (deleted) a file to the website you
will need to reconfigure the website build. To make sure you start with a clean
slate, remove the two sphinx folders in the build folder (i.e. <code class="docutils literal notranslate"><span class="pre">sphinx</span></code> and
<code class="docutils literal notranslate"><span class="pre">sphinx.html</span></code>), next rerun the cmake configuration of votca and rerun <code class="docutils literal notranslate"><span class="pre">make</span>
<span class="pre">sphinx</span></code>.</p>
</section>
<section id="editing-existing-pages">
<h2>Editing existing pages<a class="headerlink" href="#editing-existing-pages" title="Link to this heading">¶</a></h2>
<p>To edit existing pages, you only need limited knowledge of the reStructuredText
markup. You can find quick introductions <a class="reference external" href="https://docutils.sourceforge.io/docs/user/rst/quickstart.html">here</a> and <a class="reference external" href="https://docutils.sourceforge.io/docs/user/rst/quickref.html">here</a>. All pages are stored as
.rst files in the <code class="docutils literal notranslate"><span class="pre">share/sphinx</span></code> folder.</p>
</section>
<section id="writing-a-new-page">
<h2>Writing a new page<a class="headerlink" href="#writing-a-new-page" title="Link to this heading">¶</a></h2>
<p>To add a new page to the website, you will first need to decide where it belongs,
in the xtp, csg or votca repo. Once you have decided that, navigate to the corresponding folder in
<code class="docutils literal notranslate"><span class="pre">share/sphinx</span></code>. There will be either an <code class="docutils literal notranslate"><span class="pre">index.rst</span></code>
file or something like <code class="docutils literal notranslate"><span class="pre">XTP-MANUAL.rst</span></code>. This file is the main page of that repo on the website. If you look at the <code class="docutils literal notranslate"><span class="pre">index.rst</span></code> file in the <code class="docutils literal notranslate"><span class="pre">votca</span></code> repo you will
find all the subpages listed here, you need to make sure that your new page
can be found starting from this file.</p>
<p>As an example, suppose we want to add a test page, called <code class="docutils literal notranslate"><span class="pre">text.rst</span></code> to the
developers section of the website. In <code class="docutils literal notranslate"><span class="pre">votca/share/sphinx</span></code>, we would create the
new file. Next, we would update the file <code class="docutils literal notranslate"><span class="pre">votca/share/sphinx/index.rst</span></code>, we need
to add our file to the table of contents of the site. Look for the table of
contents of the development section and add the test page. It will look
something like this</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>.. toctree::
:maxdepth: 2
:hidden:
:caption: Development
DEVELOPERS_GUIDE.rst
VOTCA_LANGUAGE_GUIDE.rst
CODE_OF_CONDUCT.rst
WEBSITE_AND_DOCUMENTATION.rst
test.rst
</pre></div>
</div>
<p>After you have added content to the <code class="docutils literal notranslate"><span class="pre">test.rst</span></code> file, rebuild VOTCA and run
<code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">sphinx</span></code> to rebuild the website.</p>
</section>
<section id="changing-the-theme">
<h2>Changing the theme<a class="headerlink" href="#changing-the-theme" title="Link to this heading">¶</a></h2>
<p>To change the theme, navigate to <code class="docutils literal notranslate"><span class="pre">votca/share/sphinx/_themes</span></code>, there you will
find the <code class="docutils literal notranslate"><span class="pre">theme.css</span></code> file which you can modify to change the look and feel of
the website.</p>
</section>
<section id="publishing-your-changes">
<h2>Publishing your changes<a class="headerlink" href="#publishing-your-changes" title="Link to this heading">¶</a></h2>
<p>All the changes so far are local, to get them published simply make a pull
request in the desired repo. Once the PR is accepted, the site will
automatically be updated.</p>
</section>
<section id="more-advanced-stuff">
<h2>More Advanced Stuff<a class="headerlink" href="#more-advanced-stuff" title="Link to this heading">¶</a></h2>
<p>Except for the automatically generated pages, this website is a basic Sphinx
website, all the information you can find about Sphinx and reStructuredText on
the web is applicable here. So if you need something advanced, simply google it.</p>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="CODE_OF_CONDUCT.html" class="btn btn-neutral float-left" title="Code of Conduct" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2024, VOTCA Development Team.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>