Are there any serious C++ projects that use Sphinx alone?

[MK Latter]

I've just started to use sphinx with a C++ and I like it well enough, but I am getting a bit nervous that things are going to start falling apart because it doesn't seem to be able to handle gnarlier signatures.

I'm aware of doxygen + exhale + sphinx but that is not really a route I want to go down.

As an example, this is a perfectly valid, compilable function signature:

template<
    typename T,
    typename = std::enable_if_t<std::is_integral_v<T>, T>
>
T getIntegralArg (
    const std::string& str,
    const char ch = '\0',
    const std::string& errmsg = "Invalid argument",
    T unset = (T)0
)

I've put that like this in the documentation (the break/ident pattern works fine w/ other stuff, and putting the sig all on one line doesn't make any difference):

.. cpp:function:: template<typename T, typename = std::enable_if_t<std::is_integral_v<T>, T>> \
        T getIntegralArg (const std::string& str, const char ch = '\0', \
        const std::string& errmsg = "Invalid argument", T unset = (T)0) 

    :noindex:                                                                                                                                                                                                                 

The problem (or a symptom thereof) is that `:noindex` is interpreted literally and gets printed after the signature.  This also means I cannot use `:tparam-line-spec:`, which would be handy here.  The actual error is:

If the function has no return type:                                                                                                                      
  Error in declarator or parameters and qualifiers                                                                                                        
  Invalid definition: Expected identifier in nested name. [error at 0]                                                                                    
    :noindex:                                                                                                                                            
    ^              

Although the end product is not too zany (the actual function name is emphasized, as are the params), I'm worried more symptoms of this will keep popping up, and not being able to use `:noindex` there is a real problem.  I'd feel a little less like I'm being led down a garden path into the dark woods if I knew the C++ domain had been used for something beyond the trivial. I've searched around a bit online and glanced over the list of projects pages but nothing jumps out at me.

Is anyone aware of a non-trivial, open source C++ project (as in, actual software project, not a book about C++, etc.) that uses Sphinx and reStructuredText alone (ie., not chained to Doxygen and Exhale)?  It doesn't have to be open source as long as the documentation sources are available.

While I'm here if anyone has any ideas about getting around the problem, that would be great.  Ideally it would be nice if there were the option to manually break this down and indicate with markup the params, default values, etc.  Have I missed something there?

[Komiya Takeshi]

Hi,

On my local, it works fine without error. I copied your "cpp:function"
definition to my index.rst and build it to HTML with Sphinx-3.0.1. And
the function is not filed into index. Please check your version of
Sphinx and try it again with minimal example.

Thanks,
Takeshi KOMIYA

2020年4月19日(日) 6:59 MK Latter <halfco...@gmail.com>:

> --
> You received this message because you are subscribed to the Google Groups "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/c08a20f4-a3f6-4f28-8e71-59a08698926f%40googlegroups.com.

[MK Latter]

Hi -- thanks for the feedback!

I was using the stock Fedora version, 2.1.2

Anyway, I installed from github: `sphinx-apidoc --version` now == "sphinx-apidoc 3.1.0+/92222e9"

I recreated a fresh directory w/ `sphinx-quickstart`, and the minimal example which recreates the error looks like this:

.. cpp:function:: template<typename T, typename = std::enable_if_t<std::is_integral_v<T>, T>> \    
    T getIntegralArg (const std::string& str, const char ch = '\0', \

                              
    const std::string& errmsg = "Invalid argument", T unset = 0)                                   
    :noindex:                                                                                      
                                                                                                   
   If an option identified by ``str`` or ``ch`` is set, will try to convert that argument into     
   a ``T``.  If it is not set, returns ``unset``.  If the argument cannot be converted to a ``T``, 
   **throws** ``mishap`` using ``errmsg`` with a colon and the argument value appended.  

I had to add the add the test paragraph.  Notice it's indented...

So, problem solved (no need for indenting there, dunno why I was doing that).  This is why finding some examples using the cpp domain would be nice -- although I realize this error is just pure rST neophytism (and not posting the complete code initially).

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

[Komiya Takeshi]

It seems your mark up was wrong. Please adjust indentation of your input.
`:noindex:` option and contents of the block (If an option ...) should
have same indentation:

```

.. cpp:function:: template<typename T, typename =
std::enable_if_t<std::is_integral_v<T>, T>> \
T getIntegralArg (const std::string& str, const char ch = '\0', \
const std::string& errmsg = "Invalid argument", T unset = 0)
:noindex:

If an option identified by ``str`` or ``ch`` is set, will try to
convert that argument into
a ``T``. If it is not set, returns ``unset``. If the argument
cannot be converted to a ``T``,
**throws** ``mishap`` using ``errmsg`` with a colon and the
argument value appended.

```

Thanks,
Takeshi KOMIYA

2020年4月20日(月) 0:18 MK Latter <halfco...@gmail.com>:

> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/17d09d7a-a020-4f27-b181-1af963ddeb85%40googlegroups.com.