Doc improvements (#609)

* Add a missing nim code block marker in the first steps tutorial * Add some padding to the "Technical reference" submenu to make it easier to use The "Technical reference" submenu is horizontal which with the default padding makes it quite hard to use. It is very easy to move the mouse outside of the menu and then the menu is closed. Adding some padding makes it easier to use. The drawback is that it looks a little different than the other menus, which are vertical. The ideal solution would be to make all the menus vertical, but since the "Technical reference" submenu is 2 levels deep this is not straightforward to do. * Fix the broken "Form me on github" ribbon * Remove non-existent performance notice from the TOC * Make "What's new in Arraymancer" section "version agnostic" * Hack to make the broken documentation dark mode look acceptable This is not a proper fix, but a hack removing most color and background-color entries in the docutils.css. We should probably make a better fix but this would do for now.
mratsim · Dec 9, 2023 · 9016729 · 9016729
1 parent 12610a3
commit 9016729
Show file tree

Hide file tree

Showing 4 changed files with 25 additions and 115 deletions.
diff --git a/README.md b/README.md
@@ -221,7 +221,6 @@ Of them; she's murder'd of your galla?
 <!-- TOC -->
 
 - [Arraymancer - A n-dimensional tensor (ndarray) library.](#arraymancer---a-n-dimensional-tensor-ndarray-library)
-  - [Performance notice on Nim 0.20 & compilation flags](#performance-notice-on-nim-020--compilation-flags)
   - [Show me some code](#show-me-some-code)
     - [Tensor creation and slicing](#tensor-creation-and-slicing)
     - [Reshaping and concatenation](#reshaping-and-concatenation)
@@ -498,19 +497,10 @@ Here is a comparative table of the core features.
 | Squeezing singleton dimension                     | [x]                         | [x]                        | []                         |
 | Slicing + squeezing                               | [x]                         | []                         | []                         |
 
-## What's new in Arraymancer v0.5.1 - July 2019
+## What's new in Arraymancer
 
 The full changelog is available in [changelog.md](./changelog.md).
 
-Here are the highlights:
-
-- 0.20.x compatibility
-- Complex support
-- `Einsum`
-- Naive whitespace tokenizer for NLP
-- Fix height/width order when reading an image in tensor
-- Preview of Laser backend for matrix multiplication without SIMD autodetection (already 5x faster on integer matrix multiplication)
-
 ## 4 reasons why Arraymancer
 
 ### The Python community is struggling to bring Numpy up-to-speed

diff --git a/docs/docutils.css b/docs/docutils.css
@@ -33,9 +33,7 @@ body {
   font-weight: 400;
   font-size: 16px;
   line-height: 20px;
-  color: #444;
-  letter-spacing: 0.15px;
-  background-color: rgba(252, 248, 244, 0.45); }
+  letter-spacing: 0.15px; }
 /* Skeleton grid */
 .container {
   position: relative;
@@ -97,37 +95,28 @@ body {
 /* Customer Overrides */
 .footer {
   text-align: center;
-  color: #969696;
   padding-top: 10%; }
 p.module-desc {
   font-size: 1.1em;
-  color: #666666; }
-a.link-seesrc {
-  color: #aec7d2;
+}a.link-seesrc {
   font-style: italic; }
-a.link-seesrc:hover {
-  color: #6c9aae; }
 #toc-list {
   word-wrap: break-word; }
 ul.simple-toc {
   list-style: none; }
 ul.simple-toc a.reference-toplevel {
   font-weight: bold;
-  color: #0077b3; }
+}
 ul.simple-toc-section {
   list-style-type: circle;
-  color: #6c9aae; }
-ul.simple-toc-section a.reference {
-  color: #0077b3; }
+}
 cite {
   font-style: italic !important; }
 dt > pre {
   border-color: rgba(0, 0, 0, 0.1);
-  background-color: rgba(255, 255, 255, 0.3);
   margin: 15px 0px 5px; }
 dd > pre {
   border-color: rgba(0, 0, 0, 0.1);
-  background-color: whitesmoke;
   margin-top: 8px; }
 .item > dd {
   margin-left: 10px;
@@ -149,7 +138,6 @@ div.search-groupby {
 table.line-nums-table {
   border-radius: 4px;
   border: 1px solid #cccccc;
-  background-color: whitesmoke;
   border-collapse: separate;
   margin-top: 15px;
   margin-bottom: 25px; }
@@ -161,7 +149,6 @@ table.line-nums-table {
 .line-nums-table td.blob-line-nums {
   width: 28px; }
 .line-nums-table td.blob-line-nums pre {
-  color: #b0b0b0;
   -webkit-filter: opacity(75%);
   text-align: right;
   border-color: transparent;
@@ -173,11 +160,9 @@ table.line-nums-table {
 /* Docgen styles */
 /* Links */
 a {
-  color: #0077b3;
   text-decoration: none; }
 a:hover,
 a:focus {
-  color: #00334d;
   text-decoration: underline; }
 a:visited {
   color: #00334d; }
@@ -207,7 +192,6 @@ img {
   -ms-interpolation-mode: bicubic; }
 @media print {
   * {
-    color: black !important;
     text-shadow: none !important;
     background: transparent !important;
     box-shadow: none !important; }
@@ -368,7 +352,6 @@ pre {
   padding: 0 3px 2px;
   font-weight: 500;
   font-size: 12px;
-  color: #444444;
   -webkit-border-radius: 3px;
   -moz-border-radius: 3px;
   border-radius: 3px; }
@@ -379,9 +362,7 @@ pre {
 }
 code {
   padding: 2px 4px;
-  color: #444444;
   white-space: nowrap;
-  background-color: white;
   border: 1px solid #777777; }
 pre {
   display: inline-block;
@@ -394,7 +375,6 @@ pre {
   white-space: pre !important;
   overflow-y: hidden;
   overflow-x: visible;
-  background-color: rgba(0, 0, 0, 0.01);
   border: 1px solid #cccccc;
   -webkit-border-radius: 4px;
   -moz-border-radius: 4px;
@@ -442,8 +422,6 @@ table th, table td {
   border-top: 0; }
 .table tbody + tbody {
   border-top: 2px solid #444444; }
-.table .table {
-  background-color: rgba(252, 248, 244, 0.75); }
 .table-condensed th,
 .table-condensed td {
   padding: 4px 5px; }
@@ -518,16 +496,8 @@ table th, table td {
   -webkit-border-top-right-radius: 4px;
   border-top-right-radius: 4px;
   -moz-border-radius-topright: 4px; }
-table.docutils th {
-  background-color: #e8e8e8; }
-table.docutils tr:hover {
-  background-color: whitesmoke; }
 .table-striped tbody > tr:nth-child(odd) > td,
-.table-striped tbody > tr:nth-child(odd) > th {
-  background-color: rgba(252, 248, 244, 0.75); }
 .table-hover tbody tr:hover > td,
-.table-hover tbody tr:hover > th {
-  background-color: rgba(241, 222, 204, 0.75); }
 table td[class*="span"],
 table th[class*="span"],
 .row-fluid table td[class*="span"],
@@ -542,7 +512,6 @@ table th[class*="span"],
   font-weight: 200;
   line-height: 30px;
   color: inherit;
-  background-color: rgba(230, 197, 164, 0.75);
   -webkit-border-radius: 6px;
   -moz-border-radius: 6px;
   border-radius: 6px; }
@@ -662,7 +631,6 @@ div.sidebar {
   margin: 0 0 0.5em 1em;
   border: medium outset;
   padding: 1em;
-  background-color: rgba(252, 248, 244, 0.75);
   width: 40%;
   float: right;
   clear: right; }
@@ -759,24 +727,9 @@ pre.address {
 pre.literal-block, pre.doctest-block, pre.math, pre.code {
   margin-left: 2em;
   margin-right: 2em; }
-pre.code .ln {
-  color: grey; }
 /* line numbers */
-pre.code, code {
-  background-color: #eeeeee; }
-pre.code .comment, code .comment {
-  color: #5c6576; }
 pre.code .keyword, code .keyword {
-  color: #3B0D06;
   font-weight: bold; }
-pre.code .literal.string, code .literal.string {
-  color: #0c5404; }
-pre.code .name.builtin, code .name.builtin {
-  color: #352b84; }
-pre.code .deleted, code .deleted {
-  background-color: #DEB0A1; }
-pre.code .inserted, code .inserted {
-  background-color: #A3D289; }
 span.classifier {
   font-family: "Lato", "Helvetica Neue", "HelveticaNeue", Helvetica, Arial, sans-serif;
   font-style: oblique; }
@@ -802,8 +755,7 @@ table.docinfo {
   margin-top: 2em;
   margin-bottom: 2em;
   font-family: "Lato", "Helvetica Neue", "HelveticaNeue", Helvetica, Arial, sans-serif !important;
-  color: #444444; }
-table.docutils {
+}table.docutils {
   margin-top: 0.5em;
   margin-bottom: 0.5em; }
 table.footnote {
@@ -824,61 +776,14 @@ h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
   font-size: 100%; }
 ul.auto-toc {
   list-style-type: none; }
-span.DecNumber {
-  color: #252dbe; }
-span.BinNumber {
-  color: #252dbe; }
-span.HexNumber {
-  color: #252dbe; }
-span.OctNumber {
-  color: #252dbe; }
-span.FloatNumber {
-  color: #252dbe; }
-span.Identifier {
-  color: #3b3b3b; }
 span.Keyword {
-  font-weight: 600;
-  color: #5e8f60; }
-span.StringLit {
-  color: #a4255b; }
-span.LongStringLit {
-  color: #a4255b; }
-span.CharLit {
-  color: #a4255b; }
-span.EscapeSequence {
-  color: black; }
-span.Operator {
-  color: black; }
-span.Punctuation {
-  color: black; }
+  font-weight: 600;}
 span.Comment, span.LongComment {
   font-style: italic;
   font-weight: 400;
-  color: #484a86; }
-span.RegularExpression {
-  color: darkviolet; }
-span.TagStart {
-  color: darkviolet; }
-span.TagEnd {
-  color: darkviolet; }
-span.Key {
-  color: #252dbe; }
-span.Value {
-  color: #252dbe; }
-span.RawData {
-  color: #a4255b; }
-span.Assembler {
-  color: #252dbe; }
-span.Preprocessor {
-  color: #252dbe; }
-span.Directive {
-  color: #252dbe; }
-span.Command, span.Rule, span.Hyperlink, span.Label, span.Reference,
-span.Other {
-  color: black; }
+}
 /* Pop type, const, proc, and iterator defs in nim def blocks */
 dt pre > span.Identifier, dt pre > span.Operator {
-  color: #155da4;
   font-weight: 700; }
 dt pre > span.Identifier ~ span.Identifier, dt pre > span.Operator ~ span.Identifier {
   color: inherit;

diff --git a/docs/nimDocTemplates.nim b/docs/nimDocTemplates.nim
@@ -91,7 +91,7 @@ function main() {
 <link href='http://fonts.googleapis.com/css?family=Raleway:400,600,900' rel='stylesheet' type='text/css'/>
 <link href='http://fonts.googleapis.com/css?family=Source+Code+Pro:400,500,600' rel='stylesheet' type='text/css'/>
 
-<a href="https://github.com/mratsim/arraymancer"><img style="position: fixed; top: 0; right: 0; border: 0; z-index: 10;" src="https://camo.githubusercontent.com/652c5b9acfaddf3a9c326fa6bde407b87f7be0f4/68747470733a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f6f72616e67655f6666373630302e706e67" alt="Fork me on GitHub" data-canonical-src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png"></a>
+<a href="https://github.com/mratsim/arraymancer"><img style="position: fixed; top: 0; right: 0; border: 0; z-index: 10;" src="https://github.blog/wp-content/uploads/2008/12/forkme_right_gray_6d6d6d.png?resize=150%2C150" alt="Fork me on GitHub" data-canonical-src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png"></a>
 
 <body onload="main()">
 <div class="document" id="documentId">
@@ -115,48 +115,62 @@ const headerTmpl* = """
   <a class="pagetitle" href="index.html">Arraymancer</a>
   <span>
     <a href="#">Technical reference</a>
-    <ul class="monospace">
+    <ul class="monospace" style="padding-bottom: 15px; padding-top: 10px;">
       <span>
+      <li>
         <a href="#">Core tensor API</a>
         <ul class="monospace">
           $1
         </ul>
+      </li>
       </span>
       <span>
+      <li>
         <a href="#">Neural network API</a>
         <ul class="monospace">
           $2
         </ul>
+      </li>
       </span>
       <span>
+      <li>
         <a href="#">Linear algebra, stats, ML</a>
         <ul class="monospace">
           $3
         </ul>
+      </li>
       </span>
       <span>
+      <li>
         <a href="#">IO & Datasets</a>
         <ul class="monospace">
           $4
         </ul>
+      </li>
       </span>
       <span>
+      <li>
         <a href="#">Autograd</a>
         <ul class="monospace">
           $5
         </ul>
+      </li>
       </span>
       <span>
+      <li>
         <a href="#">Neuralnet primitives</a>
         <ul class="monospace">
           $6
         </ul>
+      </li>
       </span>
       <span>
+      <li>
         <a href="#">Other docs</a>
         <ul class="monospace">
           $7
         </ul>
+      </li>
       </span>
     </ul>
   </span>

diff --git a/docs/tuto.first_steps.rst b/docs/tuto.first_steps.rst
@@ -194,6 +194,7 @@ Take a look at the printing result of the aforementioned shape and try
 to understand the indexing shown on the top / right and how it relates
 to the different dimensions:
 
+.. code:: nim
     let t1 = toSeq(1..144).toTensor().reshape(2,3,4,3,2)
     # Tensor[system.int] of shape "[2, 3, 4, 3, 2]" on backend "Cpu"
     #                           0                            |                            1