Enhanced PHP File Manager

⬆️ Go Up (..)

📊 Server Information

Server:

nginx/1.28.0

System:

Linux 6.8.0-90-generic

PHP Version:

8.4.15

User:

alqudsvolunteers

Directory:

/home/alqudsvolunteers/rootlink/proc/thread-self/root/proc/self/root/usr/share/doc/varnish/html/phk

Free Space:

80.01 GB

🔧 Quick Actions

✏️ Editing: sphinx.html

<!DOCTYPE html>

<title>Why Sphinx and reStructuredText ? &#8212; Varnish version 7.5.0 documentation</title>
    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=e2714048" />
    
    <script src="../_static/documentation_options.js?v=8214db13"></script>
    <script src="../_static/doctools.js?v=888ff710"></script>
    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Notes from the Architect" href="notes.html" />
    <link rel="prev" title="Did you call them autocrap tools ?" href="autocrap.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="notes.html" title="Notes from the Architect"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="autocrap.html" title="Did you call them autocrap tools ?"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 7.5.0 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Poul-Hennings random outbursts</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">Why Sphinx and reStructuredText ?</a></li> 
      </ul>
    </div>

<div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="why-sphinx-and-restructuredtext">
<span id="phk-sphinx"></span><h1>Why <a class="reference external" href="http://sphinx.pocoo.org/">Sphinx</a> and <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> ?<a class="headerlink" href="#why-sphinx-and-restructuredtext" title="Link to this heading">¶</a></h1>
<p>The first school of thought on documentation, is the one we subscribe
to in Varnish right now: “Documentation schmocumentation…”  It does
not work for anybody.</p>
<p>The second school is the “Write a {La}TeX document” school, where
the documentation is seen as a stand alone product, which is produced
independently.  This works great for PDF output, and sucks royally
for HTML and TXT output.</p>
<p>The third school is the “Literate programming” school, which abandons
readability of <em>both</em> the program source code <em>and</em> the documentation
source, which seems to be one of the best access protections
one can put on the source code of either.</p>
<p>The fourth school is the “DoxyGen” school, which lets a program
collect a mindless list of hyperlinked variable, procedure, class
and filenames, and call that “documentation”.</p>
<p>And the fifth school is anything that uses a fileformat that
cannot be put into a version control system, because it is
binary and non-diff’able.  It doesn’t matter if it is
OpenOffice, LyX or Word, a non-diffable doc source is a no go
with programmers.</p>
<p>Quite frankly, none of these works very well in practice.</p>
<p>One of the very central issues, is that writing documentation must
not become a big and clear context-switch from programming.  That
precludes special graphical editors, browser-based (wiki!) formats
etc.</p>
<p>Yes, if you write documentation for half your workday, that works,
but if you write code most of your workday, that does not work.
Trust me on this, I have 25 years of experience avoiding using such
tools.</p>
<p>I found one project which has thought radically about the problem,
and their reasoning is interesting, and quite attractive to me:</p>
<ol class="arabic simple">
<li><p>TXT files are the lingua franca of computers, even if
you are logged with TELNET using IP over Avian Carriers
(Which is more widespread in Norway than you would think)
you can read documentation in a .TXT format.</p></li>
<li><p>TXT is the most restrictive typographical format, so
rather than trying to neuter a high-level format into .TXT,
it is smarter to make the .TXT the source, and reinterpret
it structurally into the more capable formats.</p></li>
</ol>
<p>In other words: we are talking about the <a class="reference external" href="http://docutils.sourceforge.net/rst.html">ReStructuredText</a> of the
Python project, as wrapped by the <a class="reference external" href="http://sphinx.pocoo.org/">Sphinx</a> project.</p>
<p>Unless there is something I have totally failed to spot, that is
going to be the new documentation platform in Varnish.</p>
<p>Take a peek at the Python docs, and try pressing the “show source”
link at the bottom of the left menu:</p>
<p>(link to random python doc page:)</p>
<blockquote>
<div><p><a class="reference external" href="https://docs.python.org/py3k/reference/expressions.html">https://docs.python.org/py3k/reference/expressions.html</a></p>
</div></blockquote>
<p>Dependency wise, that means you can edit docs with no special
tools, you need python+docutils+sphinx to format HTML and a LaTex
(pdflatex ?) to produce PDFs, something I only expect to happen
on the project server on a regular basis.</p>
<p>I can live with that, I might even rewrite the VCC scripts
from Tcl to Python in that case.</p>
<p>Poul-Henning, 2010-04-11</p>
</section>

<div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="autocrap.html"
                          title="previous chapter">Did you call them <em>autocrap</em> tools ?</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="notes.html"
                          title="next chapter">Notes from the Architect</a></p>
  </div>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../_sources/phk/sphinx.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="notes.html" title="Notes from the Architect"
             >next</a> |</li>
        <li class="right" >
          <a href="autocrap.html" title="Did you call them autocrap tools ?"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 7.5.0 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="index.html" >Poul-Hennings random outbursts</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">Why Sphinx and reStructuredText ?</a></li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
    &#169; Copyright 2010-2014, Varnish Software AS.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.
    </div>
  </body>
</html>

❌ Cancel

🗂️ Enhanced PHP File Manager

📊 Server Information

🔧 Quick Actions

✏️ Editing: sphinx.html

📤 Upload File

📁 Create Folder

📄 Create File

✏️ Rename Item

🗑️ Delete Confirmation