Discussion:
New features for Sphinx - additional roles and partial indexes
(too old to reply)
Piotr Goryl
2017-05-09 16:16:45 UTC
Permalink
Hi,

We are integrating documentation of the Tango Controls project
(http://tango-controls.readthedocs.io ). The project is quite large and
provides tools and APIs for different programming languages. Then, we are
missing some useful features, someone may already developed or thought
about:



1. Additional roles:

a. :audition: For listing intended audition of a document like:
beginner, admin, developer, user
b. :language: For listing programming languages the document/section
apply to like :c++, python, java or any

2. Possibility to generate pages/paragraphs with indexes containing
keys for selected roles or elements only, for example directives:

.. index::

:roles: term



.. api-index::

:language: c++

:module: *

:classes: [Aa]*

As it is now, for our project the autogenerated index is hard to be read.

3. possibility to display a named toctree in some other document with
some filter:

Let's assume we have a toctree in index.rst:

.. toctree::

:name: mastertoc



doc1

doc2

doc3

And somewhere in a doc4.rst:

.. insert_toc:: mastertoc

:filter-role: audition

:filter-value: admin

Then output from doc4.rst will render a table of contents with items from
mastertoc which points to sections containing :audition:`admin`

These will provide some knowledge-base functionality and make easy to
provide access to documentation from various perspectives.

What do you think about this?

How should we proceed?



Thanks in advance, best regards,

Piotr Goryl

------------------------------------------------------





e-mail: <mailto:***@3-controls.com> ***@3-controls.com

tel.: +48 795 794 004

www: <http://3-controls.com/pl/home> http://3-controls.com/pl/home



3Controls Sp. z o.o

ul. Podole 60, 30-394 Kraków, PL

NIP: 944 224 98 24, REGON: 363192231

Sąd rejonowy dla Krakowa-Śródmieścia w Krakowie, XI Wydział Gospodarczy
Krajowego Rejestru Sądowego, Numer KRS: 0000590884, Kapitał zakładowy: 10
000 PLN.

Wiadomość ta jest przeznaczona jedynie dla osoby lub podmiotu będącego jej
adresatem i moÅŒe zawierać informacje stanowiące tajemnicę przedsiębiorstwa.
Zabronione jest przeglądanie, przesyłanie, rozpowszechnianie,
wykorzystywanie tych informacji, lub podejmowanie działań na ich podstawie,
przez osoby lub podmioty inne niÅŒ zamierzony adresat. Niestosowanie się do
tego zakazu grozi odpowiedzialnością prawną. Jeśli otrzymali Państwo tę
wiadomość przez pomyłkę, prosimy o poinformowanie nadawcy i usunięcie jej
niezwłocznie z komputera.
--
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Komiya Takeshi
2017-05-11 06:13:07 UTC
Permalink
Hi Piotr,

That sounds nice. But, unfortunately, current sphinx does not have such a
categorizing/filitering feature.

Thanks,
Takeshi KOMIYA
Hi,
We are integrating documentation of the Tango Controls project (
http://tango-controls.readthedocs.io ). The project is quite large and
provides tools and APIs for different programming languages. Then, we are
missing some useful features, someone may already developed or thought
beginner, admin, developer, user
2. :language: For listing programming languages the
document/section apply to like :c++, python, java or any
2. Possibility to generate pages/paragraphs with indexes containing
:roles: term
:language: c++
:module: *
:classes: [Aa]*
As it is now, for our project the autogenerated index is hard to be read.
1. possibility to display a named toctree in some other document with
:name: mastertoc
doc1
doc2
doc3
.. insert_toc:: mastertoc
:filter-role: audition
:filter-value: admin
Then output from doc4.rst will render a table of contents with items from
mastertoc which points to sections containing :audition:`admin`
These will provide some knowledge-base functionality and make easy to
provide access to documentation from various perspectives.
What do you think about this?
How should we proceed?
Thanks in advance, best regards,
Piotr Goryl
------------------------------------------------------
*[image: logo-name]*
*tel.:* +48 795 794 004 <+48%20795%20794%20004>
*www*: http://3-controls.com/pl/home
*3Controls Sp. z o.o*
ul. Podole 60, 30-394 Kraków, PL
NIP: 944 224 98 24, REGON: 363192231
Sąd rejonowy dla Krakowa-Śródmieścia w Krakowie, XI Wydział Gospodarczy
Krajowego Rejestru Sądowego, Numer KRS: 0000590884, Kapitał zakładowy: 10
000 PLN.
*Wiadomość ta jest przeznaczona jedynie dla osoby lub podmiotu będącego
jej adresatem i moÅŒe zawierać informacje stanowiące tajemnicę
przedsiębiorstwa. Zabronione jest przeglądanie, przesyłanie,
rozpowszechnianie, wykorzystywanie tych informacji, lub podejmowanie
działań na ich podstawie, przez osoby lub podmioty inne niÅŒ zamierzony
adresat. Niestosowanie się do tego zakazu grozi odpowiedzialnością prawną.
Jeśli otrzymali Państwo tę wiadomość przez pomyłkę, prosimy o
poinformowanie nadawcy i usunięcie jej niezwłocznie z komputera.*
--
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an
For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Piotr Goryl
2017-05-16 13:56:20 UTC
Permalink
Thank you Takeshi, then I will create a feature request on the github
project (and try to schedule my time to implement it :) )

Best regards,
Piotr
Post by Komiya Takeshi
Hi Piotr,
That sounds nice. But, unfortunately, current sphinx does not have such a
categorizing/filitering feature.
Thanks,
Takeshi KOMIYA
Hi,
We are integrating documentation of the Tango Controls project (
http://tango-controls.readthedocs.io ). The project is quite large and
provides tools and APIs for different programming languages. Then, we are
missing some useful features, someone may already developed or thought
beginner, admin, developer, user
2. :language: For listing programming languages the
document/section apply to like :c++, python, java or any
2. Possibility to generate pages/paragraphs with indexes containing
:roles: term
:language: c++
:module: *
:classes: [Aa]*
As it is now, for our project the autogenerated index is hard to be read.
1. possibility to display a named toctree in some other document with
:name: mastertoc
doc1
doc2
doc3
.. insert_toc:: mastertoc
:filter-role: audition
:filter-value: admin
Then output from doc4.rst will render a table of contents with items from
mastertoc which points to sections containing :audition:`admin`
These will provide some knowledge-base functionality and make easy to
provide access to documentation from various perspectives.
What do you think about this?
How should we proceed?
Thanks in advance, best regards,
Piotr Goryl
------------------------------------------------------
*[image: logo-name]*
*tel.:* +48 795 794 004
*www*: http://3-controls.com/pl/home
*3Controls Sp. z o.o*
ul. Podole 60, 30-394 Kraków, PL
NIP: 944 224 98 24, REGON: 363192231
Sąd rejonowy dla Krakowa-Śródmieścia w Krakowie, XI Wydział Gospodarczy
Krajowego Rejestru Sądowego, Numer KRS: 0000590884, Kapitał zakładowy: 10
000 PLN.
*Wiadomość ta jest przeznaczona jedynie dla osoby lub podmiotu będącego
jej adresatem i moÅŒe zawierać informacje stanowiące tajemnicę
przedsiębiorstwa. Zabronione jest przeglądanie, przesyłanie,
rozpowszechnianie, wykorzystywanie tych informacji, lub podejmowanie
działań na ich podstawie, przez osoby lub podmioty inne niÅŒ zamierzony
adresat. Niestosowanie się do tego zakazu grozi odpowiedzialnością prawną.
Jeśli otrzymali Państwo tę wiadomość przez pomyłkę, prosimy o
poinformowanie nadawcy i usunięcie jej niezwłocznie z komputera.*
--
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an
For more options, visit https://groups.google.com/d/optout.
--
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Piotr Goryl
2017-05-16 13:53:29 UTC
Permalink
Thank you GÃŒnter,

That solves this part of my issue. Them, I will add custom roles to
rst_prolog in conf.py.

Best regards,
Piotr
Dear Piotr,
Post by Piotr Goryl
We are integrating documentation of the Tango Controls project
(http://tango-controls.readthedocs.io ). The project is quite large and
provides tools and APIs for different programming languages. Then, we
are
Post by Piotr Goryl
missing some useful features, someone may already developed or thought
beginner, admin, developer, user
b. :language: For listing programming languages the
document/section
Post by Piotr Goryl
apply to like :c++, python, java or any
The "role" directive dynamically creates a custom interpreted text role
and registers it with the parser. This means that after declaring a role
.. role:: custom
An example of using :custom:`interpreted text`
<paragraph>
An example of using
<inline classes="custom">
interpreted text
---
http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles
Can't tell about the other suggestions
...
GÃŒnter
--
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Loading...