FW: New features for Sphinx - additional roles and partial indexes

[Piotr Goryl]

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:
1. :audition: For listing intended audition of a document like: 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 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: piotr...@3-controls.com

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.

 

[Guenter Milde]

Dear Piotr,

On 2017-05-09, Piotr Goryl wrote:

> 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

You can define custom roles right in the rST source:

The "role" directive dynamically creates a custom interpreted text role
and registers it with the parser. This means that after declaring a role
like this:

.. role:: custom

the document may use the new "custom" role:

An example of using :custom:`interpreted text`

This will be parsed into the following document tree fragment:

<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

[Komiya Takeshi]

Hi Piotr,

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

Thanks,

Takeshi KOMIYA

--
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+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Piotr Goryl]

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

[Piotr Goryl]

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

To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+...@googlegroups.com.