On Sat, Jul 27, 2019 at 12:37:54PM -0300, Mauro Carvalho Chehab wrote: > 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. Ok. > > 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 Admittedly, I don't have much time at the moment to do these experiments :( > > 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. Ok, understood all these. I guess my point was all of these will need to be done to make this document useful from a ReST conversion standpoint. Until then it is probably just better off being plain text - since there are so many of those ``A -> (dep) B`` things. > > 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. Ok, got it. > 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). Yeah I don't think we want to do CSS here. So the correct thing to do would be to place all fixed-width things within double backticks, if someone had the time to do it. I am currently spending time understanding the document's content itself.. thanks for the effort, it could probably serve as a good future reference, - Joel
