-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathNotes.html
More file actions
163 lines (156 loc) · 8.3 KB
/
Notes.html
File metadata and controls
163 lines (156 loc) · 8.3 KB
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
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Notes on sphinx — DataCatalogDocs 0.2 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/nature.css" />
<link rel="stylesheet" type="text/css" href="_static/graphviz.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="canonical" href="https://dune.github.io/DataCatalogDocs/Notes.html" />
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Acknowledgements" href="Ack.html" />
<link rel="prev" title="Related documentation" href="related.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="Ack.html" title="Acknowledgements"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="related.html" title="Related documentation"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">DataCatalogDocs 0.2 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Notes on sphinx</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="notes-on-sphinx">
<h1>Notes on sphinx<a class="headerlink" href="#notes-on-sphinx" title="Permalink to this heading">¶</a></h1>
<p>This was my first sphinx project.</p>
<p>I started with the <a class="reference external" href="https://www.sphinx-doc.org/en/master/tutorial/getting-started.html">https://www.sphinx-doc.org/en/master/tutorial/getting-started.html</a> tutorial so I have a similar structure.</p>
<p>I used the napoleon theme that Igor Mandrichenko used from <a class="reference external" href="https://metacat.readthedocs.io/en/latest/">https://metacat.readthedocs.io/en/latest/</a></p>
<div class="section" id="rst-format">
<h2>rst format<a class="headerlink" href="#rst-format" title="Permalink to this heading">¶</a></h2>
<p><a class="reference external" href="https://docutils.sourceforge.io/docs/user/rst/quickstart.html">https://docutils.sourceforge.io/docs/user/rst/quickstart.html</a></p>
<p>Not my favorite -</p>
<blockquote>
<div><ul class="simple">
<li><p>the need to keep track of indentation and blank lines with poor error messages is painful</p></li>
<li><p>indentation differences when adding comments to code others wrote can be interesting</p></li>
</ul>
</div></blockquote>
</div>
<div class="section" id="github-actions">
<h2>Github actions<a class="headerlink" href="#github-actions" title="Permalink to this heading">¶</a></h2>
<p>I set up github actions to build on my github page hschellman/DataChallengeWork-loginator which is based on Jake Calcutt’s data dispatcher test system</p>
<p>The github actions had some issues:</p>
<blockquote>
<div><ul>
<li><p>It assumed the code was in main - I had to move to develop</p></li>
<li><p>I had to add a gh-pages branch by hand</p></li>
<li><p>I adapted <a class="reference external" href="https://github.com/ammaraskar/sphinx-action">https://github.com/ammaraskar/sphinx-action</a> from Ammar Askar</p></li>
<li><p>The action can be found at <a class="reference external" href="https://github.com/hschellman/DataChallengeWork-loginator/blob/develop/.github/workflows/sphinx.yml">sphinx.yml</a></p></li>
<li><p>I was not able to get the programoutput extension to work as adding a pip install for it did not work. So command line syntax is added by hand.</p></li>
<li><p>I had to add a</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">autodoc_mock_imports</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"metacat"</span><span class="p">,</span><span class="s2">"samweb_client"</span><span class="p">,</span><span class="s2">"data_dispatcher"</span><span class="p">]</span>
</pre></div>
</div>
<p>to the <cite>conf.py</cite> to avoid errors due to imports of external code. I just got blanks otherwise.</p>
</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="google-indexing-notes">
<h2>Google indexing Notes<a class="headerlink" href="#google-indexing-notes" title="Permalink to this heading">¶</a></h2>
<p># Go to <a class="reference external" href="https://search.google.com/search-console/welcome?hl=en&utm_source=wmx&utm_medium=deprecation-pane&utm_content=home">Google Search Console</a></p>
<p># choose URL prefix and enter your top level URL you will get back a</p>
<p># I github added build/html (just the directories) to github to be in the same directory as <cite>index.html</cite> and then placed the key file I got from google in that directory.</p>
<p># I then added that file to github, committed and pushed.</p>
<p># Once the action to build the docs go to the search console again and go to URL inspection. You should be able to check that the URL exists and request indexing.</p>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Notes on sphinx</a><ul>
<li><a class="reference internal" href="#rst-format">rst format</a></li>
<li><a class="reference internal" href="#github-actions">Github actions</a></li>
<li><a class="reference internal" href="#google-indexing-notes">Google indexing Notes</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="related.html"
title="previous chapter">Related documentation</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="Ack.html"
title="next chapter">Acknowledgements</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/Notes.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="Ack.html" title="Acknowledgements"
>next</a> |</li>
<li class="right" >
<a href="related.html" title="Related documentation"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">DataCatalogDocs 0.2 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Notes on sphinx</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2023, Fermi National Accelerator Laboratory.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.3.0.
</div>
</body>
</html>