deploy: a5fa09f

user_guide/docs_guidelines.html

@@ -102,6 +102,7 @@
         <nav>
           <ul>
 <li><a class="reference internal" href="#">Documentation guidelines</a><ul>
+<li><a class="reference internal" href="#before-creating-a-new-page">Before creating a new page</a></li>
 <li><a class="reference internal" href="#templates">Templates</a></li>
 <li><a class="reference internal" href="#common-sections">Common sections</a></li>
 </ul>
@@ -314,6 +315,55 @@
 <a class="icon git reference external" href="https://github.com/analogdevicesinc/hdl/tree/main/">this repository</a>, just make sure to read the general
 <a class="reference external" href="https://analogdevicesinc.github.io/doctools/docs_guidelines.html#docs-guidelines" title="(in Doctools v0.3)"><span>Documentation guidelines</span></a> first <strong>and</strong> the additional guidelines
 below specific to the HDL repository.</p>
+<section id="before-creating-a-new-page">
+<h2>Before creating a new page<a class="headerlink" href="#before-creating-a-new-page" title="Permalink to this heading">#</a></h2>
+<p>This section has the sole role to present the steps that are required to be
+able to create and build a new documentation related page. Some steps are
+recommended to be revised regularly to keep the necessary tools updated.</p>
+<p>First, make sure you have the latest version of <code class="docutils literal notranslate"><span class="pre">pip</span></code> installed. It must be
+newer than 23 version. If not, update it by running the following command:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">pip</span> <span class="o">--</span><span class="n">upgrade</span>
+</pre></div>
+</div>
+<p>Then install the necessary documentation tools by running (<a class="icon git reference external" href="https://github.com/analogdevicesinc/hdl/">HDL</a>
+repository is the working directory):</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">docs</span><span class="o">/</span>
+<span class="n">pip</span> <span class="n">install</span> <span class="o">-</span><span class="n">r</span> <span class="n">requirements</span><span class="o">.</span><span class="n">txt</span> <span class="o">--</span><span class="n">upgrade</span>
+</pre></div>
+</div>
+<p>Use the same command to regularly update the documentation tools.
+Specially if something looks broken.</p>
+<p>Before building a page, it’s recommended to build all the projects from
+<code class="docutils literal notranslate"><span class="pre">/library</span></code>. Some references (files used in specific parts of the page) are
+directly taken from the libraries’ project folder (e.g.: <code class="docutils literal notranslate"><span class="pre">/library/axi_dmac/component.xml</span></code>)
+after being built. Build the libraries by running:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">library</span><span class="o">/</span>
+<span class="n">make</span>
+</pre></div>
+</div>
+<p>Now, after the page has been written, inside <code class="docutils literal notranslate"><span class="pre">/docs</span></code> folder run the following
+command:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">docs</span><span class="o">/</span>
+<span class="n">make</span> <span class="n">html</span>
+</pre></div>
+</div>
+<p>The generated documentation will be available at <code class="docutils literal notranslate"><span class="pre">/docs/_build/html</span></code>.</p>
+<p>It’s recommended to clean the cached data when changing the document structure,
+like adding a new page or if other major changes have been made.
+This is because Sphinx rebuilds only “touched” pages and, for example,
+adding a page changes the sidebar navigation for all pages.
+This is done by running the below commands (inside <code class="docutils literal notranslate"><span class="pre">/docs</span></code> folder):</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">clean</span>
+<span class="n">make</span> <span class="n">html</span>
+</pre></div>
+</div>
+<p>Or more straight forward (clean &amp; rebuild):</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">clean</span> <span class="n">html</span>
+</pre></div>
+</div>
+<p>Make sure to read the next chapters as they provide more info on how to write
+a HDL specific Sphinx documentation page.</p>
+</section>
 <section id="templates">
 <h2>Templates<a class="headerlink" href="#templates" title="Permalink to this heading">#</a></h2>
 <p>Templates are available:</p>