ae7cb59 · searx · git.iko.soy

git.iko.soy/searx

on master help sign in

docs: reST-primer first proofreading (WIP)

ae7cb59Markus Heiser7 years ago

docs/dev/reST.rst+93−45

compare with master

unifiedsplit

@@ -28,6 +28,9 @@ The sources of Searx's documentation are located at :origin:`docs`. Run

28 - intersphinx_

29 - `Sphinx's autodoc`_

30 - `Sphinx's Python domain`_, `Sphinx's C domain`_

31+ - SVG_, ImageMagick_

32+ - DOT_, `Graphviz's dot`_, Graphviz_

33+

32.. contents:: Contents

35.. contents:: Contents

33 :depth: 3

36 :depth: 3

@@ -76,9 +79,9 @@ Admin's POV: :origin:`docs/admin`

77Developer's POV: :origin:`docs/dev`

80Developer's POV: :origin:`docs/dev`

78 Depending on the readability_ of code, a typical developer is able to read and

81 Depending on the readability_ of code, a typical developer is able to read and

79− understand source code. Describe what a item aims to do (e.g. a function),

82+ understand source code. Describe what a item aims to do (e.g. a function).

80− describe chronological order matters, describe it. Name the *out-of-limits

83+ If the chronological order matters, describe it. Name the *out-of-limits

81− condition* and all the side effects a external developer will not know.

84+ conditions* and all the side effects a external developer will not know.

83.. _reST inline markup:

86.. _reST inline markup:

@@ -254,7 +257,7 @@ Intersphinx is configured in :origin:`docs/conf.py`:

254 intersphinx_mapping = {

257 intersphinx_mapping = {

255 "python": ("https://docs.python.org/3/", None),

258 "python": ("https://docs.python.org/3/", None),

256 "flask": ("https://flask.palletsprojects.com/", None),

259 "flask": ("https://flask.palletsprojects.com/", None),

257− "jinja": ("https://jinja.palletsprojects.com/", None),

260+ "jinja": ("https://jinja.palletsprojects.com/", None),

258 "linuxdoc" : ("https://return42.github.io/linuxdoc/", None),

261 "linuxdoc" : ("https://return42.github.io/linuxdoc/", None),

259 "sphinx" : ("https://www.sphinx-doc.org/en/master/", None),

262 "sphinx" : ("https://www.sphinx-doc.org/en/master/", None),

260 }

263 }

@@ -298,6 +301,12 @@ Refer to `Sphinx Roles`_ for roles added by Sphinx.

298Figures & Images

301Figures & Images

299================

302================

300

303

304+.. sidebar:: Image processing

305+

306+ With the directives from :ref:`linuxdoc <linuxdoc:kfigure>` the build process

307+ is flexible. To get best results in the generated output format, install

308+ ImageMagick_ and Graphviz_.

309+

301Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scalable here means;

310Searx's sphinx setup includes: :ref:`linuxdoc:kfigure`. Scalable here means;

302scalable in sense of the build process. Normally in absence of a converter

311scalable in sense of the build process. Normally in absence of a converter

303tool, the build process will break. From the authors POV it’s annoying to care

312tool, the build process will break. From the authors POV it’s annoying to care

@@ -307,36 +316,44 @@ continues and scales output quality in dependence of installed image processors.

307

316

308If you want to add an image, you should use the ``kernel-figure`` and

317If you want to add an image, you should use the ``kernel-figure`` and

309``kernel-image`` directives. E.g. to insert a figure with a scalable image

318``kernel-image`` directives. E.g. to insert a figure with a scalable image

310−format use SVG (:ref:`svg_image_example`):

319+format use SVG (:ref:`svg image example`):

311

320

312.. code:: reST

321.. code:: reST

313

322

314 .. _svg image example:

323 .. _svg image example:

315

324

316 .. kernel-figure:: svg_image.svg

325 .. kernel-figure:: svg_image.svg

317− :alt: simple SVG image

326+ :alt: SVG image example

318

327

319− SVG image example

328+ simple SVG image

329+

330+ To refer the figure, a caption block is needed: :ref:`svg image example`.

320

331

321.. _svg image example:

332.. _svg image example:

322

333

323.. kernel-figure:: svg_image.svg

334.. kernel-figure:: svg_image.svg

335+ :alt: SVG image example

336+

324− :alt: simple SVG image

337+ simple SVG image

325

338

326− SVG image example

339+To refer the figure, a caption block is needed: :ref:`svg image example`.

327

340

328DOT files (aka Graphviz)

341DOT files (aka Graphviz)

329------------------------

342------------------------

330

343

331−The kernel figure (and image) directive support **DOT** formated files, see

344+With :ref:`linuxdoc:kernel-figure` reST support for **DOT** formatted files is

345+given.

332

346

333−* DOT: http://graphviz.org/pdf/dotguide.pdf

347+- `Graphviz's dot`_

334−* Graphviz: http://www.graphviz.org/content/dot-language

348+- DOT_

349+- Graphviz_

335

350

336−A simple example (:ref:`hello_dot_file`):

351+A simple example is shown in :ref:`dot file example`:

337

352

338.. code:: reST

353.. code:: reST

339

354

355+ .. _dot file example:

356+

340 .. kernel-figure:: hello.dot

357 .. kernel-figure:: hello.dot

341 :alt: hello world

358 :alt: hello world

342

359

@@ -345,6 +362,8 @@ A simple example (:ref:`hello_dot_file`):

345.. admonition:: hello.dot

362.. admonition:: hello.dot

346 :class: rst-example

363 :class: rst-example

347

364

365+ .. _dot file example:

366+

348 .. kernel-figure:: hello.dot

367 .. kernel-figure:: hello.dot

349 :alt: hello world

368 :alt: hello world

350

369

@@ -354,77 +373,100 @@ A simple example (:ref:`hello_dot_file`):

354---------------------

373---------------------

355

374

356Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the

375Embed *render* markups (or languages) like Graphviz's **DOT** is provided by the

357−``kernel-render`` directives.

376+:ref:`linuxdoc:kernel-render` directive. A simple example of embedded DOT_ is

377+shown in figure :ref:`dot render example`:

358

378

359−.. code:: reST

379+.. code-block:: rst

360

380

381+ .. _dot render example:

382+

361− .. kernel-render:: DOT markup

383+ .. kernel-render:: DOT

362− :alt: foobar digraph

384+ :alt: digraph

363− :caption: Embedded **DOT** (Graphviz) code

385+ :caption: Embedded DOT (Graphviz) code

364

386

365 digraph foo {

387 digraph foo {

366 "bar" -> "baz";

388 "bar" -> "baz";

367 }

389 }

368

390

369−How this will be rendered depends on the installed tools. If Graphviz is

391+ Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot

370−installed, you will see an vector image. If not the raw markup is inserted as

392+ render example`.

371−*literal-block* (:ref:`hello_dot_render`).

372

393

394+Please note :ref:`build tools <linuxdoc:kfigure_build_tools>`. If Graphviz_ is

395+installed, you will see an vector image. If not, the raw markup is inserted as

396+*literal-block*.

397+

373−.. admonition:: DOT markup

398+.. admonition:: kernel-render DOT

374 :class: rst-example

399 :class: rst-example

375

400

376− .. _hello_dot_render:

401+ .. _dot render example:

377

402

378 .. kernel-render:: DOT

403 .. kernel-render:: DOT

379− :alt: foobar digraph

404+ :alt: digraph

380− :caption: Embedded **DOT** (Graphviz) code

405+ :caption: Embedded DOT (Graphviz) code

381

406

382 digraph foo {

407 digraph foo {

383 "bar" -> "baz";

408 "bar" -> "baz";

384 }

409 }

385

410

386−The *render* directive has all the options known from the *figure* directive,

411+ Attribute ``caption`` is needed, if you want to refer the figure: :ref:`dot

387−plus option ``caption``. If ``caption`` has a value, a *figure* node is

412+ render example`.

388−inserted. If not, a *image* node is inserted. A ``caption`` is also needed, if

389−you want to refer it (:ref:`hello_svg_render`).

390−

391

413

392``kernel-render`` SVG

414``kernel-render`` SVG

393---------------------

415---------------------

394

416

417+A simple example of embedded SVG_ is shown in figure :ref:`svg render example`:

418+

395−.. code:: reST

419+.. code-block:: rst

420+

421+ .. _svg render example:

396

422

397− .. kernel-render:: SVG markup

423+ .. kernel-render:: SVG

398 :caption: Embedded **SVG** markup

424 :caption: Embedded **SVG** markup

399 :alt: so-nw-arrow

425 :alt: so-nw-arrow

400..

426..

401

427

402− .. code:: xml

428+ .. code:: xml

403

429

404 <?xml version="1.0" encoding="UTF-8"?>

430 <?xml version="1.0" encoding="UTF-8"?>

405− <svg xmlns="http://www.w3.org/2000/svg"

431+ <svg xmlns="http://www.w3.org/2000/svg" version="1.1"

406− version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">

432+ baseProfile="full" width="70px" height="40px"

433+ viewBox="0 0 700 400"

434+ >

435+ <line x1="180" y1="370"

436+ x2="500" y2="50"

407− <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>

437+ stroke="black" stroke-width="15px"

438+ />

408− <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>

439+ <polygon points="585 0 525 25 585 50"

440+ transform="rotate(135 525 25)"

441+ />

409 </svg>

442 </svg>

410

443

411−.. admonition:: SVG markup

444+.. admonition:: kernel-render SVG

412 :class: rst-example

445 :class: rst-example

413

446

414− .. _hello_svg_render:

447+ .. _svg render example:

415

448

416 .. kernel-render:: SVG

449 .. kernel-render:: SVG

417 :caption: Embedded **SVG** markup

450 :caption: Embedded **SVG** markup

418 :alt: so-nw-arrow

451 :alt: so-nw-arrow

419

452

420 <?xml version="1.0" encoding="UTF-8"?>

453 <?xml version="1.0" encoding="UTF-8"?>

421− <svg xmlns="http://www.w3.org/2000/svg"

454+ <svg xmlns="http://www.w3.org/2000/svg" version="1.1"

422− version="1.1" baseProfile="full" width="70px" height="40px" viewBox="0 0 700 400">

455+ baseProfile="full" width="70px" height="40px"

456+ viewBox="0 0 700 400"

457+ >

458+ <line x1="180" y1="370"

459+ x2="500" y2="50"

423− <line x1="180" y1="370" x2="500" y2="50" stroke="black" stroke-width="15px"/>

460+ stroke="black" stroke-width="15px"

461+ />

424− <polygon points="585 0 525 25 585 50" transform="rotate(135 525 25)"/>

462+ <polygon points="585 0 525 25 585 50"

463+ transform="rotate(135 525 25)"

464+ />

425 </svg>

465 </svg>

426

466

427

467

468+

469+

428.. _reST lists:

470.. _reST lists:

429

471

430List markups

472List markups

@@ -551,7 +593,7 @@ are mappings from field names to field bodies. They marked up like this:

551 :fieldname: Field content

593 :fieldname: Field content

552 :foo: first paragraph in field foo

594 :foo: first paragraph in field foo

553

595

554− second paragraph in field foo

596+ second paragraph in field foo

555

597

556 :bar: Field content

598 :bar: Field content

557

599

@@ -561,7 +603,7 @@ are mappings from field names to field bodies. They marked up like this:

561 :fieldname: Field content

603 :fieldname: Field content

562 :foo: first paragraph in field foo

604 :foo: first paragraph in field foo

563

605

564− second paragraph in field foo

606+ second paragraph in field foo

565

607

566 :bar: Field content

608 :bar: Field content

567

609

@@ -684,3 +726,9 @@ Admonitions: :dudir:`hint`, :dudir:`note`, :dudir:`tip` :dudir:`attention`,

684.. _docutils: http://docutils.sourceforge.net/docs/index.html

726.. _docutils: http://docutils.sourceforge.net/docs/index.html

685.. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html

727.. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html

686.. _linuxdoc: https://return42.github.io/linuxdoc

728.. _linuxdoc: https://return42.github.io/linuxdoc

729+.. _SVG: https://www.w3.org/TR/SVG11/expanded-toc.html

730+.. _DOT: https://graphviz.gitlab.io/_pages/doc/info/lang.html

731+.. _`Graphviz's dot`: https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf

732+.. _Graphviz: https://graphviz.gitlab.io

733+

734+.. _ImageMagick: https://www.imagemagick.org