Em Sat, 27 Jul 2019 14:14:53 +0000 Joel Fernandes <joel@xxxxxxxxxxxxxxxxx> escreveu: > On Fri, Jul 26, 2019 at 04:01:37PM -0300, Mauro Carvalho Chehab wrote: > > The books at tools/memory-model/Documentation are very well > > formatted. Congrats to the ones that wrote them! > > > > The manual conversion to ReST is really trivial: > > > > - Add document titles; > > - change the bullets on some lists; > > - mark code blocks. > > Thanks so much, some feedback: > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> > > (1) > I could not find the table of contents appear in the HTML output for this. > Basically this list in the beginning doesn't render: > 1. INTRODUCTION > 2. BACKGROUND > 3. A SIMPLE EXAMPLE > 4. A SELECTION OF MEMORY MODELS > 5. ORDERING AND CYCLES Yes. It is written as a comment, like: .. foo This is a comment block Everything on this block won't be parsed. So it won't be parsed, but having a TOC like this isn't need, as Sphinx generates it automatically via "toctree" markup. > Could we add a proper TOC with sections? My motivation for ReST here would be > to make the sections jumpable since it is a large document. Just change the toctree depth at index.rst to 2 and you'll see an index produced by Sphinx with both levels 1 (doc name) and level 2 (chapters): .. toctree:: :maxdepth: 2 > Also could we make the different sections appear as a tree in the left > sidebar? The sidebar follows the maxdepth too. > > (2) Arguably several function names in the document HTML output should appear > in monospace fonting and/or referring to the documentation for real function > names, but these can be fixed as we go, I guess. If you want monospaced fonts, just use: ``monospaced_symbol_foo`` within any paragraph, or place the monospaced data inside a code-block: :: This will be monospaced. > > (3) Things like smp_load_acquire() and spin_lock() should probably refer to > the documentation for those elsewhere.. Jon added an automarkup extension on Kernel 5.2. So, all functions that are defined elsewhere will automatically generate an hyperlink. For that to happen, you need to add the kernel-doc markup at the *.h or *.c file where the function is declared and use the kernel-doc markup somewhere within the Kernel Documentation/. > > (4) I would argue that every occurence of > A ->(some dependency) B should be replaced with fixed size font in the HTML > results. Just place those with ``A -> (some dependency)``. This will make them use a fixed size font. > Arguably it is better IMO if the whole document is fixed size font in the > HTML output because so many things need to be fixed size, but that my just be > my opinion. Just my 2 cents here, but having the entire document using a fixed size font makes it more boring to read. Having just the symbols with a fixed size is a common convention used on technical books, and helps to make easier to identify the symbols while reading the docs. That's said, Sphinx doesn't have any tag to switch the font for the entire document. All it can be done is to define a CSS and apply it for the doc - or to place everything within a code-block, with will suppress all markup tags, including cross-references for functions. The problem with CSS is that you need to write both an html CSS file and add LaTeX macros associated to this "CSS style" (technically, LaTeX doesn't have a CSS concept, but Sphinx emulates it). Thanks, Mauro
