[sphinx-users] Re: Documentation about the built in search?

[bradley...@gmail.com]

I have a sphinx wrapper  and wanted to configure the sphinx search to use 
all the words in the index but I could not figure out how to get sphinx to 
do this. ( For the sphinx wrapper, the words in the index are the words in 
the headings, titles, and page names.)

I used raw html  to get the search I wanted. For example,  here is the 
search for the sphinx wrapper
https://xrst.readthedocs.io/latest/xrst_search.html

It would be nice if there was a way to get the sphinx search to function 
like the example above ?

On Thursday, April 7, 2022 at 9:29:39 PM UTC-7 Charles Bouchard-Légaré 
wrote:

> I have also been looking into it lately and the only things I found was... 
> reading the source code.
>
> I was looking into trying to improve the search widget, trying to get 
> closer to what is available with MkDocs (modal results as you types, etc, 
> see screenshot below). 
>
> *Here is what I found about Sphinx' search:*
>
>- The Javascript code for doing the actual search against the index is 
>at sphinx/themes/basic/static/searchtools.js 
>
> 
>- The generation of the index is done at build time and the code is 
>sphinx/search/__init__.py 
>
>- Sphinx does not only «full text search»
>   - First, look into «object» (like Python functions and such)
>  - The displayed result is built on the domain's display name and 
>  object type localized name
>  - No excerpt are provided here (which is kind of sad)
>  - Then, try full text search
>  - An excerpt built from text around the result is displayed
>  - I am no expert in full-text search, but it looks both simple 
>  and pretty standard, we more priority on terms from titles.  There 
> is a 
>  good stemmer for several languages.
>   - Sphinx' search clearly this is *not* an API
>   - Sphinx' search is not much configurable and does not seems to be 
>   part of a public API for users or extension developers to build on.
>   - When writing a new Domain, objects a provided by the get_objects 
>method 
>
> 
>  
>(which must be provided by your implementation)
>   - It returns an iterable of «objects», a 6-tuple
>   - The last item priority determine how important an object is 
>   regarding search
>   - The URL built by the search result depend on the first, second 
>   and 5th item
>  - fullname «Fully qualified name.»
>  - dispname «Name to display when searching/linking.»
>  - anchor «The anchor name for the object.»
>   - In my custom Domain, search-generated URLs don't target the 
>   actual documented object. I still need to investigate how the Directive 
>   implementation, these three «object tuple» attribute and the search 
> work 
>   together. It seems to have still a few Python-specifics in there.
>- As part of WebSupport, Sphinx provides a few utilities to enable 
>server-side search 
>
> .
>  
>Personally, this is not interesting to me at the moment.
>
> *For comparison, here is what I found about MkDocs*
>
>- Unless specific plugins, only full text search is done.
>- It uses lunr.js 
>   - The documents MkDocs registers to lunr.js are, from my 
>   understanding
>  - All pages
>  - All sub sections, recursively
>  - Which means some text is added multiple times.  I suspect 
>  subsection are prioritized in the results
>  - Each item provides two "fields": title and text, somewhat like 
>  Sphinx.
>   - By default, they used to use lunr.py 
>    for pregenerating the 
>   index.  This pregeneration is configurable.
>   - This is deprecated now because lunr.py has binary transitive 
>  dependencies for non-english languages and this makes MkDocs harder 
> to use 
>  for Alpine Docker image users.
>  - They offer now to subprocess lunr.js with Nodejs
>  - The index can also be generated by Web workers 
>  
> *Other info I found:*
>
>- ReadTheDocs has quite interesting search features 
>
>- Someone did made a lunr.js extension 
> for Sphinx, but 
>only indexing "objects" in a separate custom search widget. Not actively 
>maintained.
>- I've looked into trying lunr in Sphinx for fulltext.  Building an 
>Index would be quite simple with a EnvironmentCollector, but 

[sphinx-users] Re: Sphinx example sites using Algolia search engine, others?

[bradley...@gmail.com]

xrst builds its own search page for each web site it builds; e.g., see
https://xrst.readthedocs.io/latest/xrst_search.html

What I could not figure out (from the sphinx documentation) was how to 
replace the normal search with this page ?

On Thursday, May 25, 2023 at 5:45:16 AM UTC-7 Mikko Ohtamaa wrote:

> Hi all,
>
> As Sphinx's default search is not very powerful, I am looking an 
> alternative plug-and-play solution to improve the usability of the search.
>
> Are there example sites using different search backends for Sphinx?
>
> I have one site using Algolia, who seem to dominate in this space, but are 
> there other example sites or example search engines that would not take too 
> much time to set up?
>
> https://mcdreforged.readthedocs.io/en/latest/
>
> https://github.com/readthedocs/sphinx_rtd_theme/issues/761
>
> Using sphinx_rtd_theme and furo themes.
>
> Br,
> Mikko
>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/078d2475-ea19-46a7-906c-e0930b3edffcn%40googlegroups.com.

[sphinx-users] Re: Using Sphinx Search

[bradley...@gmail.com]

I have added the automatic generation, by xrst, of a sphinx web page that 
does this type of search using raw html and javascript; e.g., see
https://xrst.readthedocs.io/xrst_search.html

On Wednesday, October 4, 2023 at 8:06:30 AM UTC-7 bradley...@gmail.com 
wrote:

> I would like to restrict the search to only match keywords in each page. 
> The  keywords in the search box would be separated by spaces with an 
> implicit and between them. The more keywords, the fewer matches. In 
> addition, when I get a match, I would like to see the title (first heading) 
> for the page and all the keywords for that page.  Is there some way to get 
> sphinx to do this ? 
>
> Currently I specify the keywords using:
>
> .. meta::
>:keywords: word_1, word_2, ...
>
> But I could easily use some other method of marking up the keywords in the 
> rst files.
>
>
>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/d275cceb-c11a-4b2a-bf32-f229b0f85b97n%40googlegroups.com.

[sphinx-users] Using Sphinx Search

[bradley...@gmail.com]

I would like to restrict the search to only match keywords in each page. 
The  keywords in the search box would be separated by spaces with an 
implicit and between them. The more keywords, the fewer matches. In 
addition, when I get a match, I would like to see the title (first heading) 
for the page and all the keywords for that page.  Is there some way to get 
sphinx to do this ? 

Currently I specify the keywords using:

.. meta::
   :keywords: word_1, word_2, ...

But I could easily use some other method of marking up the keywords in the 
rst files.


-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/57de17a4-017a-47e5-bec4-47fb50ac8885n%40googlegroups.com.

[sphinx-users] Looking for an example that customizes the sphinx search box

[bradley...@gmail.com]

 I am looking for an example that customizes the sphinx search.

My goal is to only match words that are in the index roles for a page.
In addition, I would like all (and only) the index words for each page to 
be displayed when the matching pages are displayed.
Even better would be if the matching pages displayed in a drop down box and 
changed as one added or removed words from the search.

It would be OK if the words in the headings, instead of the index words, 
were used for each page.

I think that perhaps 
https://www.sphinx-doc.org/en/master/usage/advanced/websupport/searchadapters.html#search-adapters
Can do what I am looking for, or perhaps it is already done for me if I 
choose the right theme ?

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/89e6f773-3ec0-4618-969d-1d646fd435a2n%40googlegroups.com.

[sphinx-users] Re: The xrst sphinx wrapper

[bradley...@gmail.com]

This is not a problem with readthedoc, it is a problem with how firefox 
handles redirects.

xrst is using a redirect in the index.html file to load any page that one 
chooses on the command line; e.g.,
```
 window.location.href="user-guide.html" 
```
The problem is that once firefox gets the redirect it never reloads it when 
it changes.
I had to clear my cache to get it to reload.

On Friday, January 6, 2023 at 5:52:12 AM UTC-7 bradley...@gmail.com wrote:

> I changed the name user_guide to user-guide (as a test) and there seems to 
> be a problem with readthedocs. 
> The link
> https://xrst.readthedocs.io/en/latest/index.html
> works fine and gets to the user-guide.html page, but the link
> https://xrst.readthedocs.io/
> tries to go to the old user_guide.html page (which is no longer there).
>
> On Sunday, January 1, 2023 at 10:22:00 AM UTC-7 bradley...@gmail.com 
> wrote:
>
>> This is an announcement for the first stable release of xrst
>> https://xrst.readthedocs.io
>>
>> This wrapper was motivated by cases like the GNU Scientific library, 
>> which is written in C, uses sphinx for its documentation, and has its 
>> documentation in separate files from the corresponding source code. 
>>
>> The following link lists the features that xrst adds to sphinx:
>> https://xrst.readthedocs.io/en/latest/purpose.html
>>
>> The following is a list of problems and possible improvements:
>> https://xrst.readthedocs.io/en/latest/wish_list.html
>>
>>
>>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/8467625b-6638-4ef9-939c-0dcd075d1decn%40googlegroups.com.

[sphinx-users] Re: The xrst sphinx wrapper

[bradley...@gmail.com]

I changed the name user_guide to user-guide (as a test) and there seems to 
be a problem with readthedocs. 
The link
https://xrst.readthedocs.io/en/latest/index.html
works fine and gets to the user-guide.html page, but the link
https://xrst.readthedocs.io/
tries to go to the old user_guide.html page (which is no longer there).

On Sunday, January 1, 2023 at 10:22:00 AM UTC-7 bradley...@gmail.com wrote:

> This is an announcement for the first stable release of xrst
> https://xrst.readthedocs.io
>
> This wrapper was motivated by cases like the GNU Scientific library, which 
> is written in C, uses sphinx for its documentation, and has its 
> documentation in separate files from the corresponding source code. 
>
> The following link lists the features that xrst adds to sphinx:
> https://xrst.readthedocs.io/en/latest/purpose.html
>
> The following is a list of problems and possible improvements:
> https://xrst.readthedocs.io/en/latest/wish_list.html
>
>
>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/2ef7df5d-bac4-4967-8127-b8ec8444e4d1n%40googlegroups.com.

[sphinx-users] The xrst sphinx wrapper

[bradley...@gmail.com]

This is an announcement for the first stable release of xrst
https://xrst.readthedocs.io

This wrapper was motivated by cases like the GNU Scientific library, which 
is written in C, uses sphinx for its documentation, and has its 
documentation in separate files from the corresponding source code. 

The following link lists the features that xrst adds to sphinx:
https://xrst.readthedocs.io/en/latest/purpose.html

The following is a list of problems and possible improvements:
https://xrst.readthedocs.io/en/latest/wish_list.html


-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/6a17c8d9-4421-408a-9ebe-6dabea832403n%40googlegroups.com.

Re: [sphinx-users] Could not lex literal_block as "cpp"

[bradley...@gmail.com]

Thanks:
It appears that my system has automatically upgraded to pygments 2.13.0 and 
the problem is no longer there.

On Sunday, November 27, 2022 at 9:47:16 AM UTC-7 je...@abou-samra.fr wrote:

>
>
> Le 16/11/2022 à 22:54, bradley...@gmail.com a écrit :
>
> Suppose the following file is named soruce/temp.cpp:
>
> double f(
> double x // '(x)
> )
>{  return x; }
>
> If I put the following command in my sphinx-quickstart source/index.rst 
> file below the toctree command:
>
> .. literalinclude:: temp.cpp
>:language: cpp
>
> and I execute the following command
>
> sphinx-build -b html source build
> 
> I get the following error message
>
>...  sphinx/source/index.rst:14: WARNING: Could not lex literal_block 
> as "cpp". ...
>
> If, in temp.cpp,  I change the '(x) to (x) , the warning goes away and the 
> file gets highlighted. It seems to me this change should not make any 
> difference because it is inside a C++ comment.
>
> --
>
>
>
> This is a bug that was fixed in recent versions of Pygments. Try upgrading 
> (python3 -m pip install --upgrade pygments).
>
>
>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/bdd2edbf-b1d2-40dc-8270-94543d23e340n%40googlegroups.com.

[sphinx-users] Re: Could not lex literal_block as "cpp"

[bradley...@gmail.com]

The following test indicates this is a problem with sphinx and not 
pygments. 
I copied and pastered source/temp.cpp into the pygments Demo 
https://pygments.org/demo/
with Language C++ and it works fine:

On Wednesday, November 16, 2022 at 2:54:14 PM UTC-7 bradley...@gmail.com 
wrote:

> Suppose the following file is named soruce/temp.cpp:
>
> double f(
> double x // '(x)
> )
>{  return x; }
>
> If I put the following command in my sphinx-quickstart source/index.rst 
> file below the toctree command:
>
> .. literalinclude:: temp.cpp
>:language: cpp
>
> and I execute the following command
>
> sphinx-build -b html source build
> 
> I get the following error message
>
>...  sphinx/source/index.rst:14: WARNING: Could not lex literal_block 
> as "cpp". ...
>
> If, in temp.cpp,  I change the '(x) to (x) , the warning goes away and the 
> file gets highlighted. It seems to me this change should not make any 
> difference because it is inside a C++ comment.
>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/3114c31e-ffeb-4445-8fff-acb341b67bbfn%40googlegroups.com.

[sphinx-users] Could not lex literal_block as "cpp"

[bradley...@gmail.com]

Suppose the following file is named soruce/temp.cpp:

double f(
double x // '(x)
)
   {  return x; }

If I put the following command in my sphinx-quickstart source/index.rst 
file below the toctree command:

.. literalinclude:: temp.cpp
   :language: cpp

and I execute the following command

sphinx-build -b html source build

I get the following error message

   ...  sphinx/source/index.rst:14: WARNING: Could not lex literal_block as 
"cpp". ...

If, in temp.cpp,  I change the '(x) to (x) , the warning goes away and the 
file gets highlighted. It seems to me this change should not make any 
difference because it is inside a C++ comment.

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/6afbb6eb-33ad-45c5-a22b-a98d2fc7236fn%40googlegroups.com.

Re: [sphinx-users] Fixed Width Paragraph with italic, bold, and normal font

[bradley...@gmail.com]

Thanks, the following input

.. parsed-literal:: 

**variable_**on**e** = constant_one( **variable_two** ) 
**variable_three** = constant_two( **variable_four** ) 

generates the output I was looking for
On Monday, September 5, 2022 at 11:17:53 AM UTC-7 matthia...@gmail.com 
wrote:

> On Sun, Sep 4, 2022 at 3:27 PM bradley...@gmail.com
>  wrote:
> >
> > How in sphinx does one create a paragraph that uses a fixed width for 
> all characters and allows one to switch between normal, italic, and bold 
> fonts.
>
> You should try the parsed-literal directive:
>
> https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal
>
> But be warned about this issue:
>
> https://github.com/sphinx-doc/sphinx/issues/2167
>
> cheers,
> Matthias
>
> > This quesiton is similar to the following question on stackoverflow .
> >
> > --
> > 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/a7a88ff0-6bcc-4f5c-87c3-8b7696aee44an%40googlegroups.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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/b0f820e9-62aa-4249-9ef0-6c88d4aa6ff4n%40googlegroups.com.

[sphinx-users] Re: Duplicate target name, cannot be used as a unique reference:

[bradley...@gmail.com]

It appears that Sphinx does not work with headings that have a underbar at 
the end ? It this is the case, a better warning message would be helpful.

On Friday, September 16, 2022 at 12:08:01 PM UTC-7 bradley...@gmail.com 
wrote:

> Suppose that the file index.rst contains the text below. This results (for 
> me) in the error message above. In addition the local table off contents 
> has variable_name for the link to the heading variable_name_. Is this 
> expected  and if so, how should one document a case like this ?
>
> Test Headings
> #
>
> .. contents::
> :local:
>
> Arguments to Constructor
> 
>
> variable_name
> =
> Discussion of this argument
>
> Memember Variables
> **
>
> variable_name_
> ==
> Discussion of this member variable
>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/50be2405-785c-48c0-80d7-0169b46a200fn%40googlegroups.com.

[sphinx-users] Duplicate target name, cannot be used as a unique reference:

[bradley...@gmail.com]

Suppose that the file index.rst contains the text below. This results (for 
me) in the error message above. In addition the local table off contents 
has variable_name for the link to the heading variable_name_. Is this 
expected  and if so, how should one document a case like this ?

Test Headings
#

.. contents::
:local:

Arguments to Constructor


variable_name
=
Discussion of this argument

Memember Variables
**

variable_name_
==
Discussion of this member variable

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/922ac9aa-a669-46c7-a4c3-31e0165e9962n%40googlegroups.com.

[sphinx-users] Fixed Width Paragraph with italic, bold, and normal font

[bradley...@gmail.com]

How in sphinx does one create a paragraph that uses a fixed width for all 
characters and allows one to switch between normal, italic, and bold fonts.

This quesiton is similar to the following question on stackoverflow 

 
.

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/a7a88ff0-6bcc-4f5c-87c3-8b7696aee44an%40googlegroups.com.

[sphinx-users] Re: New PDF builder: Sphinx-SimplePDF

[bradley...@gmail.com]

Looks very nice, but it seems to display the latex input instead of rending 
the equations (as intended by latex) ?

Sorry if you got two copies of this post, I was trying to fix a typo in the 
previous version.


On Friday, August 26, 2022 at 1:34:13 AM UTC-7 Daniel Woste wrote:

> Hi all,
>
> just wanted to let you know that a new PDF builder is available, which 
> hopefully makes some stuff easier regarding PDF generation: 
> Sphinx-SimplePDF.
>
> Docs HTML : https://sphinx-simplepdf.readthedocs.io/
>
> Only 2 commands are needed to get a PDF out of your existing docs:
> 1) pip install sphinx-simplepdf
> 2) make simplepdf
>
> Sphinx-SimplePDF provides already a nice-looking, modern theme (incl. 
> front and back cover).  See following link as example.
>
> Docs PDF: 
> https://sphinx-simplepdf.readthedocs.io/en/latest/_static/Sphinx-SimplePDF.pdf
>
> Theming is done via HTML and CSS, so no Latex is involved.
> (Backend is based on weasyprint)
> As it is based on HTML, all extensions should be supported out of the box.
>
> Main colors and images can be configured inside your conf.py file. 
> So no CSS knowledge is needed for generic changes.
>
> I hope you like it and that it is useful for your project.
> Happy to get some feedback :)
>
> Have a great day,
>   Daniel
>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/279e92f9-ca20-4f1e-ae94-24111b1f04afn%40googlegroups.com.

[sphinx-users] Re: New PDF builder: Sphinx-SimplePDF

[bradley...@gmail.com]

Looks very nice, but it does seems to just display the latex input instead 
of rending the equations (as intended by latex) ?

On Friday, August 26, 2022 at 1:34:13 AM UTC-7 Daniel Woste wrote:

> Hi all,
>
> just wanted to let you know that a new PDF builder is available, which 
> hopefully makes some stuff easier regarding PDF generation: 
> Sphinx-SimplePDF.
>
> Docs HTML : https://sphinx-simplepdf.readthedocs.io/
>
> Only 2 commands are needed to get a PDF out of your existing docs:
> 1) pip install sphinx-simplepdf
> 2) make simplepdf
>
> Sphinx-SimplePDF provides already a nice-looking, modern theme (incl. 
> front and back cover).  See following link as example.
>
> Docs PDF: 
> https://sphinx-simplepdf.readthedocs.io/en/latest/_static/Sphinx-SimplePDF.pdf
>
> Theming is done via HTML and CSS, so no Latex is involved.
> (Backend is based on weasyprint)
> As it is based on HTML, all extensions should be supported out of the box.
>
> Main colors and images can be configured inside your conf.py file. 
> So no CSS knowledge is needed for generic changes.
>
> I hope you like it and that it is useful for your project.
> Happy to get some feedback :)
>
> Have a great day,
>   Daniel
>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/97a32900-45b1-4b1b-b0fa-ae1146b09c32n%40googlegroups.com.

[sphinx-users] Re: theme sidebar configuration

[bradley...@gmail.com]

It appears that sphinx_book_theme uses much more disk space that 
sphinx_rtd_theme. Here is a comparison for a project I am working on:

sphinx_book_theme
du -s doc
6008doc

sphinx_rtd_theme
du -s doc
2324doc

I am using gh-pages on github to display documentation and am concerned 
about the size of the footprint of the documentation.

On Sunday, August 21, 2022 at 12:44:43 PM UTC-7 Max Lange wrote:

> The sphinx_book_theme 
> <https://github.com/executablebooks/sphinx-book-theme> supports this.
>
> On Saturday, August 20, 2022 at 10:00:08 PM UTC-7 bradley...@gmail.com 
> wrote:
>
>> The furo theme (with its default setting) has two side bars. The left 
>> side bar contains the contents tree for the web pages. The right side bar 
>> contains the contents tree for each individual page.  This is a very nice 
>> feature because headings within a web page do not affect the overall 
>> contents tree. This facilitates moving a sub tree to a different location 
>> in the web page contents tree (in the spirit of incremental iterative 
>> development).
>>
>> Are there other themes that enable one to see these two trees separately ?
>>
>>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/bd689062-5091-4650-b9de-1f999e069b8an%40googlegroups.com.

[sphinx-users] Re: theme sidebar configuration

[bradley...@gmail.com]

Thanks for the pointer. I was able to get the desired result using

html_theme_options = {
'show_toc_level' : 4
 }

I was not able to find documentatiton for this setting on
https://sphinx-book-theme.readthedocs.io/en/stable/customize/index.html

But I did find it in
https://github.com/executablebooks/sphinx-book-theme/blob/master/docs/conf.py

On Sunday, August 21, 2022 at 12:44:43 PM UTC-7 Max Lange wrote:

> The sphinx_book_theme 
> <https://github.com/executablebooks/sphinx-book-theme> supports this.
>
> On Saturday, August 20, 2022 at 10:00:08 PM UTC-7 bradley...@gmail.com 
> wrote:
>
>> The furo theme (with its default setting) has two side bars. The left 
>> side bar contains the contents tree for the web pages. The right side bar 
>> contains the contents tree for each individual page.  This is a very nice 
>> feature because headings within a web page do not affect the overall 
>> contents tree. This facilitates moving a sub tree to a different location 
>> in the web page contents tree (in the spirit of incremental iterative 
>> development).
>>
>> Are there other themes that enable one to see these two trees separately ?
>>
>>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/24de0a0e-a91e-406e-a2e4-87dca6e3268dn%40googlegroups.com.

[sphinx-users] theme sidebar configuration

[bradley...@gmail.com]

The furo theme (with its default setting) has two side bars. The left side 
bar contains the contents tree for the web pages. The right side bar 
contains the contents tree for each individual page.  This is a very nice 
feature because headings within a web page do not affect the overall 
contents tree. This facilitates moving a sub tree to a different location 
in the web page contents tree (in the spirit of incremental iterative 
development).

Are there other themes that enable one to see these two trees separately ?

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/f9927505-ca2d-41f7-8c42-108ca2ad1106n%40googlegroups.com.

[sphinx-users] Anchors used for links to headings

[bradley...@gmail.com]

I want to generate links from web pages that are not generated by sphinx, 
to headings and sub-headings in web pages that are generated by sphinx.

I have noticed that sphinx automatically generates anchors for such links.
For example, using sphinx v4.1.2, if the test_link.rst file contains the 
text

Title
#

Heading 1
*

Heading 2
*

Heading-2
*

The the file test_link.hmtl generated by sphinx will contain the following
link anchor for the headings in test_link.html:

Title: href="#title"
Heading 1: href="#heading-1"
Heading 2: href="#heading-2"
Heading-2: href="#id1"

It seems that the heading text has been converted to lower case and that
spaces ' ' have been converted to dashes '-'. It also seems if a conversion
would yield the same value as a previous coversion, then a numbered id, that
increases by one each time it is needed, is used for the link.

1.  Are these conversion rules for link anchors correct ?

2.  Are there ther conversion rules; e.g., other times that the numbered ids
are inserted (and hence increase by one).

2.  Are these rules part of the sphinx API; i.e., will it be the same in 
future versions of sphinx ?

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/fb03ed68-56ee-4611-af6b-a246bb7c7bben%40googlegroups.com.

Re: [sphinx-users] Problem With \newcommand in latexpdf

[bradley...@gmail.com]

I came up with what seemed to me to be a simpler solution. I put the macros 
in my preamble.rst between two comment lines that I could recognize and 
remove easily using sed. I then used a wrapper script to build the pdf that 
fist removed the macors in preamble.rst, then build the pdf, and then 
replaced the original preamble.rst. Here is my preamble.rst:

.. |space| unicode:: 0xA0 
.. |tab| replace:: |space| |space| |space| |space| 
 
.. comment BEGIN_LATEX_MACROS 
These latex macros must also be defined in latex_elements in 
conf.py 
 
.. rst-class:: hidden 
 
:math:`\newcommand{\B}[1]{ {\bf #1} }` 
:math:`\newcommand{\R}[1]{ {\rm #1} }` 
 
.. comment END_LATEX_MACROS 

My problem is that I would like to use ReadtheDocs to display my 
documentation, but I do no know how to get it to run a script between 
building the html and build the pdf ?

Perhaps there is a way in preamble.rst to conditionaly include the macros 
depending on if latex or html conversion is being done ?

On Wednesday, November 25, 2020 at 8:34:57 PM UTC-7 ds04...@gmail.com wrote:

> On Wed, Aug 12, 2020, 5:19 AM bradley...@gmail.com  
> wrote:
>
>> The index.rst file below demonstrates that \newcommand does not work with 
>> latexpdf.
>>
>>  Below is my conf.py file 
>> # For conf.py documentation see
>> # http://www.sphinx-doc.org/en/master/config
>> #
>> project   = 'newcommand'
>> extensions = [
>> 'sphinx.ext.mathjax',
>> ]
>> - Below is my index.rst file -
>> Problem With \newcommand in latexpdf
>> 
>> This file builds just file,
>> and displays as intended, with ``make html``,
>> but with ``make latexpdf`` it generates and
>> ``Undefined control sequence.`` error for the
>> macro ``\B``.
>>
>> Define Latex Macro
>> **
>> ``:math: \newcommand{\B}[1]{{\bf #1}}``
>> :math:`\newcommand{\B}[1]{{\bf #1}}`
>>
>> Use Latex Macro \B
>> **
>> ``:math: f : \B{R} \rightarrow \B{R}``
>> :math:`f : \B{R} \rightarrow \B{R}`
>>
>> This File
>> *
>> .. literalinclude:: index.rst
>>
>> -- 
>> 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/92312617-c0dc-4c14-9d41-068e79f7bd76n%40googlegroups.com
>>  
>> <https://groups.google.com/d/msgid/sphinx-users/92312617-c0dc-4c14-9d41-068e79f7bd76n%40googlegroups.com?utm_medium=email_source=footer>
>> .
>>
>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/e9e4ce70-4e21-4665-8104-81b0d9f87c38n%40googlegroups.com.

[sphinx-users] Re: esaping { and } in :samp: role

[bradley...@gmail.com]

Sorry for the mistake in the example code, the input should end in a 
backquote; i.e.,
   :samp:`\{ {x} , {y} \}`

On Saturday, November 14, 2020 at 4:35:53 AM UTC-7 bradley...@gmail.com 
wrote:

> In the following documentation
>
> https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-samp
>
> It says:
> Changed in version 1.8: Allowed to escape curly braces with backslash
>
> I therefore expect the input
>:samp:`\{ {x}, {y} \}'
> to have the first { in normal font, but in my tests it comes out in italic 
> font. 
>
> How do I escape the { and } characters so that they display instead of 
> switching font in the :samp: role ?
>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/f75ab8e5-0324-4622-a107-cca2b7600a98n%40googlegroups.com.

[sphinx-users] esaping { and } in :samp: role

[bradley...@gmail.com]

In the following documentation
https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-samp

It says:
Changed in version 1.8: Allowed to escape curly braces with backslash

I therefore expect the input
   :samp:`\{ {x}, {y} \}'
to have the first { in normal font, but in my tests it comes out in italic 
font. 

How do I escape the { and } characters so that they display instead of 
switching font in the :samp: role ?

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/ba1df058-193d-489f-b89b-433ab8526f68n%40googlegroups.com.

Re: [sphinx-users] What Sphinx changes on gh-pages branch

[bradley...@gmail.com]

Thanks: Removing the `.doctrees` directory works.
I thought `.doctrees` might be used for  navigating or searching or both.

On Thursday, November 12, 2020 at 10:51:54 AM UTC-7 i.tk...@gmail.com wrote:

> Hi,
>
> The files under `.doctrees` directory are generated on building as
> intermediate file. So they don't need to be committed to your repo. So
> please remove them before committing (or give `-d` option to create it
> outside of your repo).
>
> Thanks,
> Takeshi KOMIYA
>
> 2020年10月20日(火) 23:58 bradley...@gmail.com :
> >
> > I am using sphinx to build my github pages.
> > When a file .rst changes, I get changes in the following files:
> >
> > .doctrees/environment.pickle
> > .doctrees/.doctree
> > _sources/.rst.txt
> > objects.inv
> > .html
> >
> > I like to update my documentation corresponding to the master branch 
> (the bleeding edge) often. This includes changes to the release notes that 
> say what is different each time. I am worried that worried that this will 
> cause the size of my github repository to grow significantly. Has this been 
> a problem ? Is sphinx designed with this use case in mind ?
> >
> > --
> > 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/03c1a340-f3f3-4ce0-a372-9b5100cea7e5n%40googlegroups.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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/17285f26-d2bc-4953-86da-ae24ca12ff84n%40googlegroups.com.

[sphinx-users] Re: ANN: "insipid" Sphinx theme, release 0.2.0

[bradley...@gmail.com]

I have tried insipid and I have two questions:

1. How does on change the  color  used for in-line literal font; e.g., 
``test``  ?

2. Is there a way to only use titles in the navigation, like read rtd_theme 
does when titles_only is True; see
https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#theme-options

On Wednesday, October 21, 2020 at 3:16:47 AM UTC-7 matthia...@gmail.com 
wrote:

> Dear list.
>
> I've already announced my new Sphinx theme "insipid" right here two months 
> ago.
>
> Since then, I've tuned the colors to make them less annoying and more
> insipid. I hope you like them!
>
> Here's the theme documentation (and at the same time a usage example):
>
> https://insipid-sphinx-theme.readthedocs.io/
>
> The usage should be really simple:
>
> 1. Install the Python package insipid-sphinx-theme
> 2. Add html_theme = 'insipid' to your conf.py
> 3. Run Sphinx!
>
> It would be great if you could try it out and give feedback (either
> here on the list or at
> https://github.com/mgeier/insipid-sphinx-theme/issues)!
>
> There are certainly many things that can (and should) be improved, I'd
> love to hear your suggestions.
>
> There aren't a lot of example projects yet, I've just tried it out on
> a few projects I'm currently working on:
>
> https://nbsphinx.readthedocs.io/
> https://python-sounddevice.readthedocs.io/en/latest/
> https://python-rtmixer.readthedocs.io/
> https://jackclient-python.readthedocs.io/
> https://mg.readthedocs.io/
> https://jupyter-format.readthedocs.io/
> https://audioscenedescriptionformat.readthedocs.io/
> https://splines.readthedocs.io/
>
> I've mostly tested the theme on multiple browsers on Linux and
> Android, it would be great to get some coverage on Windows, macOS, iOS
> and whatever other OS you are using!
>
> cheers,
> Matthias
>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/9664c5b7-0f1f-49ee-8f38-cd5e97b188b0n%40googlegroups.com.

[sphinx-users] Space Between Italic and Literal Words

[bradley...@gmail.com]

Using rst how does one avoid a space between an italic word and a literal 
word ?

The attached rst file demonstrates the problem:

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/b8f5c22a-7077-40c4-aeda-baa2ab31fe66n%40googlegroups.com.
Space Between Italic and Literal Words
##

Notation



is a space character


is a back quote character


is a star character

Problem
***
The input 

| prefix/lib

generates the following output:

| *prefix* ``/lib`` 

I would like to know how to avoid the space between *prefix* and ``/lib`` ?

[sphinx-users] What Sphinx changes on gh-pages branch

[bradley...@gmail.com]

I am using sphinx to build my github pages. 
When a file .rst changes, I get changes in the following files:

.doctrees/environment.pickle
.doctrees/.doctree
_sources/.rst.txt
 objects.inv 
.html

I like to update my documentation corresponding to the master branch (the 
bleeding edge) often. This includes changes to the release notes that say 
what is different each time. I am worried that worried that this will cause 
the size of my github repository to grow significantly. Has this been a 
problem ? Is sphinx designed with this use case in mind ?

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/03c1a340-f3f3-4ce0-a372-9b5100cea7e5n%40googlegroups.com.

Re: [sphinx-users] make latexpdf

[bradley...@gmail.com]

There is still something more than just run pdflatex multiple times that 
make inside _build/latex does because the index is missing if one only runs 
pdflatex. I discussed this in more detail in my second message above.

On Tuesday, September 15, 2020 at 8:33:22 AM UTC-7 Jeff McKenna wrote:

> Thanks KOMIYA-san for mentioning that make inside _build/latex handles 
> pdflatex multiple times, as I've been manually doing this for years, ha.  
>
> -jeff
>
>
>
> On Sat, Sep 12, 2020 at 11:01 PM Komiya Takeshi  wrote:
>
>> Hi,
>>
>> You need to run pdflatex command multiple times to build complete PDF 
>> file.
>> For more detail, please read the following article.
>>
>> https://www.systutorials.com/why-do-i-need-to-run-latex-bibtex-three-times-to-make-everything-look-good/
>>
>> Instead of pdflatex command, you can use `make` command under the
>> _build/latex directory.
>> It invokes pdflatex multiple times automatically. I hope it helps you.
>>
>> Thanks,
>> Takeshi KOMIYA
>>
>> 2020年9月13日(日) 6:32 bradley...@gmail.com :
>> >
>> >
>> > I am trying to figure out how to reproduce
>> > make latexpdf
>> > with separate calls to first build the latex and then run pdflatex. I 
>> want to do this so I can directly modify the latex between the sphinx-build 
>> and pdflatex (to accomplish things that are not supported by sphinx).
>> >
>> > I am using
>> > sphinx-build -b latex . _build/latex
>> > cd _build/latex
>> > pdflatex .tex
>> > where  is the value of project in my conf.py. When I do 
>> this I get the error message
>> > No file .ind
>> > and the index is missing from my pdf.
>> >
>> > What am I missing here ?
>> >
>> > --
>> > 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/3540f597-7857-46b8-878f-1ede81adedean%40googlegroups.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/CAFmkQAOO_xCb4LULBUYbgtuUfMHFtTh%2Bg2ewH%2BOrTU%3DC3Tb5%2BA%40mail.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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/71ce01b4-34b0-4b5f-b38d-af15f3a73b40n%40googlegroups.com.

Re: [sphinx-users] make latexpdf

[bradley...@gmail.com]

The following seems to work for me:
rm -r _build
sphinx-build -b latex . _build/latex
cd _build/latex
make .pdf


On Sunday, September 13, 2020 at 6:07:07 AM UTC-7 bradley...@gmail.com 
wrote:

> Thanks for the response. I knew one has to run pdflatex twice (when any of 
> the links change) and should have put that in my report above. I did not 
> know three times was necessary in some cases. Unfortunately, this does not 
> fix the problem; i.e., the following
> rm -r _build
> sphinx-build -b latex . _build/latex
> cd _build/latex
> pdflatex .tex 
> pdflatex .tex 
> pdflatex .tex 
> has the same result
> No file .ind
> in the file file 
> _build/latex/.log 
> and the index is not in the file
> _build/latex/.pdf
>
> I added the
> rm -r _build
> because you must first delete the old _build directory to test this. If 
> you don't, the old .ind file from the previous
> make latexpdf
> gets used by the
> pdflatex .tex
> command.
>
>
> On Saturday, September 12, 2020 at 7:01:16 PM UTC-7 i.tk...@gmail.com 
> wrote:
>
>> Hi, 
>>
>> You need to run pdflatex command multiple times to build complete PDF 
>> file. 
>> For more detail, please read the following article. 
>>
>> https://www.systutorials.com/why-do-i-need-to-run-latex-bibtex-three-times-to-make-everything-look-good/
>>  
>>
>> Instead of pdflatex command, you can use `make` command under the 
>> _build/latex directory. 
>> It invokes pdflatex multiple times automatically. I hope it helps you. 
>>
>> Thanks, 
>> Takeshi KOMIYA 
>>
>> 2020年9月13日(日) 6:32 bradley...@gmail.com : 
>> > 
>> > 
>> > I am trying to figure out how to reproduce 
>> > make latexpdf 
>> > with separate calls to first build the latex and then run pdflatex. I 
>> want to do this so I can directly modify the latex between the sphinx-build 
>> and pdflatex (to accomplish things that are not supported by sphinx). 
>> > 
>> > I am using 
>> > sphinx-build -b latex . _build/latex 
>> > cd _build/latex 
>> > pdflatex .tex 
>> > where  is the value of project in my conf.py. When I do 
>> this I get the error message 
>> > No file .ind 
>> > and the index is missing from my pdf. 
>> > 
>> > What am I missing here ? 
>> > 
>> > -- 
>> > 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/3540f597-7857-46b8-878f-1ede81adedean%40googlegroups.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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/f757d7b1-f28d-4534-aff3-829b2e125e6dn%40googlegroups.com.

Re: [sphinx-users] make latexpdf

[bradley...@gmail.com]

Thanks for the response. I knew one has to run pdflatex twice (when any of 
the links change) and should have put that in my report above. I did not 
know three times was necessary in some cases. Unfortunately, this does not 
fix the problem; i.e., the following
rm -r _build
sphinx-build -b latex . _build/latex
cd _build/latex
pdflatex .tex 
pdflatex .tex 
pdflatex .tex 
has the same result
No file .ind
in the file file 
_build/latex/.log 
and the index is not in the file
_build/latex/.pdf

I added the
rm -r _build
because you must first delete the old _build directory to test this. If you 
don't, the old .ind file from the previous
make latexpdf
gets used by the
pdflatex .tex
command.


On Saturday, September 12, 2020 at 7:01:16 PM UTC-7 i.tk...@gmail.com wrote:

> Hi,
>
> You need to run pdflatex command multiple times to build complete PDF file.
> For more detail, please read the following article.
>
> https://www.systutorials.com/why-do-i-need-to-run-latex-bibtex-three-times-to-make-everything-look-good/
>
> Instead of pdflatex command, you can use `make` command under the
> _build/latex directory.
> It invokes pdflatex multiple times automatically. I hope it helps you.
>
> Thanks,
> Takeshi KOMIYA
>
> 2020年9月13日(日) 6:32 bradley...@gmail.com :
> >
> >
> > I am trying to figure out how to reproduce
> > make latexpdf
> > with separate calls to first build the latex and then run pdflatex. I 
> want to do this so I can directly modify the latex between the sphinx-build 
> and pdflatex (to accomplish things that are not supported by sphinx).
> >
> > I am using
> > sphinx-build -b latex . _build/latex
> > cd _build/latex
> > pdflatex .tex
> > where  is the value of project in my conf.py. When I do 
> this I get the error message
> > No file .ind
> > and the index is missing from my pdf.
> >
> > What am I missing here ?
> >
> > --
> > 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/3540f597-7857-46b8-878f-1ede81adedean%40googlegroups.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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/eb86a3a7-7115-4282-8d71-abc323eb2233n%40googlegroups.com.

[sphinx-users] make latexpdf

[bradley...@gmail.com]

I am trying to figure out how to reproduce
make latexpdf 
with separate calls to first build the latex and then run pdflatex. I want 
to do this so I can directly modify the latex between the sphinx-build and 
pdflatex (to accomplish things that are not supported by sphinx). 

I am using
sphinx-build -b latex . _build/latex
cd _build/latex
pdflatex .tex 
where  is the value of project in my conf.py. When I do this 
I get the error message
No file .ind 
and the index is missing from my pdf. 

What am I missing here ? 

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/3540f597-7857-46b8-878f-1ede81adedean%40googlegroups.com.

[sphinx-users] latexpdf table of contents and order of text

[bradley...@gmail.com]

When generating html files, the information in the current section comes 
before the information for each of its child sections; i.e., the document 
is designed to be read from any node down the tree.

If I put my toctree commands directly after the title for a section, 
latexpdf puts the information for the children before the information for 
the parent.

If I put my toctree commands at the end of a section, latexpdf's table of 
contents puts the children for the current section below the last heading 
for the current section, instead of directly below the title for the 
current section.

How do I get latexpdf to generate output like the children are at the end 
of each section and table of contents like the children are under the title 
for each section ?

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/1cf894e0-0e88-4523-b184-82e5cc628531n%40googlegroups.com.

[sphinx-users] Re: Problem With \newcommand in latexpdf

[bradley...@gmail.com]

I am trying to get the same source code to produce both the html pages and 
a pdf document. I think this is one of the advantages of sphinx ? I was not 
expecting the scope of commands to be different for the two cases, html and 
pdf.

I am using a file called preamble.rst to get my definitions for the entire 
document inside each html page (this includes other commands besides latex 
command). If I use the latex_elements as suggested above, I have to include 
the definitions in preamble.rst to build html files and remove them to 
build latexpdf files. While this doable, it would seem there should be a 
simpler way.

Perhaps I should ask this with another conservation ?
I have noticed something strange in the latexpdf output (now that I can get 
it) . The table of contents in the pdf file only seems to include the 
toctree command in the index.rst file, and not the toctree commands in 
other files that get included. I am using the Read The Docs theme and the 
htm_theme_options has 'titles_only' is set to True.


On Thursday, August 13, 2020 at 12:16:22 AM UTC-7 jfbu wrote:

> Hi,
>
> Le 12/08/2020 à 14:19, bradley...@gmail.com a écrit :
> > The index.rst file below demonstrates that \newcommand does not work 
> with latexpdf.
> > 
> >  Below is my conf.py file 
> > # For conf.py documentation see
> > # http://www.sphinx-doc.org/en/master/config
> > #
> > project   = 'newcommand'
> > extensions = [
> > 'sphinx.ext.mathjax',
> > ]
> > - Below is my index.rst file -
> > Problem With \newcommand in latexpdf
> > 
> > This file builds just file,
> > and displays as intended, with ``make html``,
> > but with ``make latexpdf`` it generates and
> > ``Undefined control sequence.`` error for the
> > macro ``\B``.
> > 
> > Define Latex Macro
> > **
> > ``:math: \newcommand{\B}[1]{{\bf #1}}``
> > :math:`\newcommand{\B}[1]{{\bf #1}}`
> > 
> > Use Latex Macro \B
> > **
> > ``:math: f : \B{R} \rightarrow \B{R}``
> > :math:`f : \B{R} \rightarrow \B{R}`
> > 
>
> the LaTeX has scope limiting constructs such as "environments"
> but also equations, inclusive of inline mathematics
>
> (delimited in the file in LaTeX mark-up produced by make latex by \( ... 
> \) delimiters)
>
> you must locate the \newcommand outside of such scope delimited location
>
> either via
>
> .. raw:: latex
>
> \newcommand{\B}[1]{{\bf #1}}
>
> before it is used (and only once)
>
> or in conf.py
>
> latex_elements = {
> 'preamble': r"\newcommand{\B}[1]{{\bf #1}}",
> }
>
> which is a priori better location, recommended for that usage.
>
>
> Once this is done do not put any other \newcommand{\B} as this will 
> generate an error.
>
> Notice that \bf mark-up has been deprecated by LaTeX developers
> and perhaps {\mathbf{#1}} is more legit
>
> latex_elements = {
> 'preamble': r"\newcommand{\B}[1]{\mathbf{#1}}",
> }
>
>
> or, if you use xelatex with unicode-math, perhaps \symbf
>
>
> Besides LaTeX normative gurus will try to discourage you to define a 
> one-letter
> command such as \B. (the rationale being that depending on language perhaps
> the one-letter command has a meaning already ; anyway if it does the 
> \newcommand
> will then raise an error so you will know).
>
>
> Jean-François
>
>
>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/5ae0887c-7d93-4fa1-bdb7-63c0b8efd5dcn%40googlegroups.com.

[sphinx-users] Problem With \newcommand in latexpdf

[bradley...@gmail.com]

The index.rst file below demonstrates that \newcommand does not work with 
latexpdf.

 Below is my conf.py file 
# For conf.py documentation see
# http://www.sphinx-doc.org/en/master/config
#
project   = 'newcommand'
extensions = [
'sphinx.ext.mathjax',
]
- Below is my index.rst file -
Problem With \newcommand in latexpdf

This file builds just file,
and displays as intended, with ``make html``,
but with ``make latexpdf`` it generates and
``Undefined control sequence.`` error for the
macro ``\B``.

Define Latex Macro
**
``:math: \newcommand{\B}[1]{{\bf #1}}``
:math:`\newcommand{\B}[1]{{\bf #1}}`

Use Latex Macro \B
**
``:math: f : \B{R} \rightarrow \B{R}``
:math:`f : \B{R} \rightarrow \B{R}`

This File
*
.. literalinclude:: index.rst

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/92312617-c0dc-4c14-9d41-068e79f7bd76n%40googlegroups.com.

Re: [sphinx-users] Vertical space after latex command

[bradley...@gmail.com]

Thanks for the suggestion. I used the instructions on 
https://blog.readthedocs.com/custom-css-and-js-in-sphinx/
to add a style sheet and it worked.

To be specific, I added the file _static/css/custom.css with the following 
text:

/* preamble used to add hidden class */

.hidden {
display: None;
}

I changed my latex macro to

.. rst-class:: hidden

:math:`\newcommand{\B}[1]{ {\bf #1} }`


I added the following at the end of my conf.py
 
# -- These folders are copied to the documentation's HTML output 

html_static_path = [ '_static' ]

# -- These paths are either relative to html_static_path 

# or fully qualified paths (eg. https://...)
html_css_files = [
'css/custom.css',
]


 
On Tuesday, August 11, 2020 at 3:54:34 AM UTC-7 matthia...@gmail.com wrote:

> On Tue, Aug 4, 2020 at 1:41 AM bradley...@gmail.com wrote:
> >
> > I like to put macro definitions at the top of my latex files. It seems 
> that sphinx generates empty vertical space when I do this in rst files. 
> Attached is a conf.py and index.rst file that demonstrates this problem:
> >
> > Is there some place I can put a set of latex macro definitions and not 
> have this problem ?
>
> It's a bit of a hack, but you can try something like this:
>
> 
>
> .. raw:: html
>
> 
>
> :math:`\newcommand{\B}[1]{{\bf #1}}`
>
> .. raw:: html
>
> 
>
> 
>
> Alternatively, you can do it with a CSS class, which makes the .rst
> file a bit simpler:
>
> 
> .. rst-class:: hidden
>
> :math:`\newcommand{\B}[1]{{\bf #1}}`
> 
>
> ... but you need to defined some custom CSS:
>
> 
> .hidden {
> display: none;
> }
> 
>
> cheers,
> Matthias
>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/4664d0c2-14c8-4430-87a7-626d9336304an%40googlegroups.com.

[sphinx-users] Vertical space after latex command

[bradley...@gmail.com]

I like to put macro definitions at the top of my latex files. It seems that 
sphinx generates empty vertical space when I do this in rst files. Attached 
is a conf.py and index.rst file that demonstrates this problem:

Is there some place I can put a set of latex macro definitions and not have 
this problem ?

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/5e3ae8c2-d593-4afc-b628-1bf1ff2bdb76n%40googlegroups.com.
# For conf.py documentation see
# http://www.sphinx-doc.org/en/master/config
#
project   = 'latex_space'
extensions = [
'sphinx.ext.mathjax',
]
exclude_patterns = [
'_build', 'Thumbs.db', '.DS_Store',
]
:math:`\newcommand{\B}[1]{{\bf #1}}`

Vertical Space After Latex Command
==
I often put macros definitions at the top of my latex files; e.g,
I have put the following definition at the top of this rst file:

| \:math\: \`\\newcommand{\\B}[1]{{\\bf #1}}\`

This latex command has no output, but it causes more white space to be placed
before the title in the html version of this file (as generated by sphinx).
If you delete the first line of this file (which containts the latex command)
the title in the html version will move up.

Re: [sphinx-users] Using rst file names for navigation

[bradley...@gmail.com]

I have figured out a solution to my problem.  I put an extra header at the 
top of every file that is the rst file name without extension. I also use 
the following setting in my conf.py file:

html_theme = 'sphinx_rtd_theme'
html_theme_options = {
'navigation_depth' : -1   ,
'titles_only'  : True ,
}

For an example of the result; see
https://bradbell.github.io/cppad_py/doc/html/xsrst/cppad_py.html

This uses the xsrst program which extras sphinx rst files from source code; 
see
https://bradbell.github.io/cppad_py/doc/html/xsrst/xsrst_py.html


On Wednesday, July 8, 2020 at 11:24:28 AM UTC-7 bradley...@gmail.com wrote:

> I am using toctree in each section that has children as you describe 
> above. When I view the section with that toctree entry, I would like the 
> navigation links in the left column to corresponds to the names in the 
> toctree command; i.e., use 'first' instead of the headings in the file 
> first.rst, 'second' instead of the headings in section.rst, and so on.
>
> Right now, I get all the headings in the root section of my entire 
> document, instead of the bread crumb file names up to the root section and 
> the children below.
>
>
>
> On Wednesday, July 8, 2020 at 6:52:43 AM UTC-7 Stefano David wrote:
>
>> HI,
>>
>>
>> On Wednesday, 8 July 2020 13:23:02 UTC+2, bradley...@gmail.com wrote:
>>>
>>> I have been using my own documentation system for years and am writing a 
>>> program to convert sphinx so that it is easier for others to edit my 
>>> documentation, and so that I no longer have to maintain it (It was written 
>>> years ago in C).  In this system one has a title and an abbreviated title 
>>> for each section (web page) and the abbreviated titles are used for 
>>> navigation.
>>>
>>> Here is an example use of my documentation system: 
>>> https://bradbell.github.io/dismod_at/doc/data_table.py.htm
>>>
>>> I am asking how to best reproduce this navigation functionality in 
>>> sphinx ?
>>>
>> If I understand correctly your requirement, given that you have files 
>> first.rst, second.rst, third.rst you should be able to add them to the 
>> toctree as follows to get the desired effect:
>>
>> .. toctree::
>>first.rst 
>>second.rst 
>>third.rst 
>>
>> HTH,
>> Stefano
>>
>>>
>>> On Wednesday, July 8, 2020 at 12:04:58 AM UTC-7 Matt from Documatt wrote:
>>>
>>>> Hi Bradley!
>>>> Question #1 - You can't use filename as document title. First section 
>>>> found in document will become a document title.
>>>>
>>>> Baz will be document title:
>>>>
>>>> foo
>>>>
>>>> bar
>>>>
>>>> baz
>>>> ===
>>>>
>>>> but document title is usually at the very top of the file:
>>>>
>>>> baz
>>>> ===
>>>>
>>>> foo
>>>>
>>>> bar
>>>>
>>>> Question 2 - you speak about breadcrumb navigation. If you have 
>>>> correctly described relations among documents using toctree directive, 
>>>> many 
>>>> themes use breadcrumb > like > you > mention. Important here is to 
>>>> emphasize that structure of book is described with toctree directive, not 
>>>> with on-disk representation of document files.
>>>>
>>>> Matt
>>>> blog.documatt.com
>>>>
>>>> On Tue, Jul 7, 2020 at 8:47 PM Bradley Bell  
>>>> wrote:
>>>>
>>>>> I only use one heading at the top level for each file. 
>>>>> The file name (without the .rst extansion) is a shorthand for the 
>>>>> heading at the top of each file. 
>>>>>
>>>>> I would like to use the file names, and only the file names in the 
>>>>> navigation tree. 
>>>>> The navigation for a section would show its children, and possible 
>>>>> grandchilren, down to some configurable level. 
>>>>>
>>>>> It would also be nice for the navigation to also show all the 
>>>>> ancestors above the current section; i.e., 
>>>>> the position of the current web page in the documentaion tree (using 
>>>>> the file names).
>>>>> I currently do this with links at the top of each section; e.g.,
>>>>>grand_parent > parent > current
>>>>> where grand_parent, parent, and current are the corresponding file 
>>>>> names and

Re: [sphinx-users] Using rst file names for navigation

[bradley...@gmail.com]

I am using toctree in each section that has children as you describe above. 
When I view the section with that toctree entry, I would like the 
navigation links in the left column to corresponds to the names in the 
toctree command; i.e., use 'first' instead of the headings in the file 
first.rst, 'second' instead of the headings in section.rst, and so on.

Right now, I get all the headings in the root section of my entire 
document, instead of the bread crumb file names up to the root section and 
the children below.



On Wednesday, July 8, 2020 at 6:52:43 AM UTC-7 Stefano David wrote:

> HI,
>
>
> On Wednesday, 8 July 2020 13:23:02 UTC+2, bradley...@gmail.com wrote:
>>
>> I have been using my own documentation system for years and am writing a 
>> program to convert sphinx so that it is easier for others to edit my 
>> documentation, and so that I no longer have to maintain it (It was written 
>> years ago in C).  In this system one has a title and an abbreviated title 
>> for each section (web page) and the abbreviated titles are used for 
>> navigation.
>>
>> Here is an example use of my documentation system: 
>> https://bradbell.github.io/dismod_at/doc/data_table.py.htm
>>
>> I am asking how to best reproduce this navigation functionality in sphinx 
>> ?
>>
> If I understand correctly your requirement, given that you have files 
> first.rst, second.rst, third.rst you should be able to add them to the 
> toctree as follows to get the desired effect:
>
> .. toctree::
>first.rst 
>second.rst 
>third.rst 
>
> HTH,
> Stefano
>
>>
>> On Wednesday, July 8, 2020 at 12:04:58 AM UTC-7 Matt from Documatt wrote:
>>
>>> Hi Bradley!
>>> Question #1 - You can't use filename as document title. First section 
>>> found in document will become a document title.
>>>
>>> Baz will be document title:
>>>
>>> foo
>>>
>>> bar
>>>
>>> baz
>>> ===
>>>
>>> but document title is usually at the very top of the file:
>>>
>>> baz
>>> ===
>>>
>>> foo
>>>
>>> bar
>>>
>>> Question 2 - you speak about breadcrumb navigation. If you have 
>>> correctly described relations among documents using toctree directive, many 
>>> themes use breadcrumb > like > you > mention. Important here is to 
>>> emphasize that structure of book is described with toctree directive, not 
>>> with on-disk representation of document files.
>>>
>>> Matt
>>> blog.documatt.com
>>>
>>> On Tue, Jul 7, 2020 at 8:47 PM Bradley Bell  
>>> wrote:
>>>
>>>> I only use one heading at the top level for each file. 
>>>> The file name (without the .rst extansion) is a shorthand for the 
>>>> heading at the top of each file. 
>>>>
>>>> I would like to use the file names, and only the file names in the 
>>>> navigation tree. 
>>>> The navigation for a section would show its children, and possible 
>>>> grandchilren, down to some configurable level. 
>>>>
>>>> It would also be nice for the navigation to also show all the ancestors 
>>>> above the current section; i.e., 
>>>> the position of the current web page in the documentaion tree (using 
>>>> the file names).
>>>> I currently do this with links at the top of each section; e.g.,
>>>>grand_parent > parent > current
>>>> where grand_parent, parent, and current are the corresponding file 
>>>> names and grand_parent and parent are links.
>>>>
>>>>
>>>> How do I do this using sphinx ? 
>>>>
>>>> -- 
>>>> 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/284685c5-9204-4ebf-bbe5-f505b01475bfo%40googlegroups.com
>>>>  
>>>> <https://groups.google.com/d/msgid/sphinx-users/284685c5-9204-4ebf-bbe5-f505b01475bfo%40googlegroups.com?utm_medium=email_source=footer>
>>>> .
>>>>
>>>

-- 
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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/7bd70665-adce-4644-8bd6-070b76897199n%40googlegroups.com.

Re: [sphinx-users] Using rst file names for navigation

[bradley...@gmail.com]

I have been using my own documentation system for years and am writing a 
program to convert sphinx so that it is easier for others to edit my 
documentation, and so that I no longer have to maintain it (It was written 
years ago in C).  In this system one has a title and an abbreviated title 
for each section (web page) and the abbreviated titles are used for 
navigation.

Here is an example use of my documentation system: 
https://bradbell.github.io/dismod_at/doc/data_table.py.htm

I am asking how to best reproduce this navigation functionality in sphinx ?

On Wednesday, July 8, 2020 at 12:04:58 AM UTC-7 Matt from Documatt wrote:

> Hi Bradley!
> Question #1 - You can't use filename as document title. First section 
> found in document will become a document title.
>
> Baz will be document title:
>
> foo
>
> bar
>
> baz
> ===
>
> but document title is usually at the very top of the file:
>
> baz
> ===
>
> foo
>
> bar
>
> Question 2 - you speak about breadcrumb navigation. If you have correctly 
> described relations among documents using toctree directive, many themes 
> use breadcrumb > like > you > mention. Important here is to emphasize that 
> structure of book is described with toctree directive, not with on-disk 
> representation of document files.
>
> Matt
> blog.documatt.com
>
> On Tue, Jul 7, 2020 at 8:47 PM Bradley Bell  wrote:
>
>> I only use one heading at the top level for each file. 
>> The file name (without the .rst extansion) is a shorthand for the heading 
>> at the top of each file. 
>>
>> I would like to use the file names, and only the file names in the 
>> navigation tree. 
>> The navigation for a section would show its children, and possible 
>> grandchilren, down to some configurable level. 
>>
>> It would also be nice for the navigation to also show all the ancestors 
>> above the current section; i.e., 
>> the position of the current web page in the documentaion tree (using the 
>> file names).
>> I currently do this with links at the top of each section; e.g.,
>>grand_parent > parent > current
>> where grand_parent, parent, and current are the corresponding file names 
>> and grand_parent and parent are links.
>>
>>
>> How do I do this using sphinx ? 
>>
>> -- 
>> 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/284685c5-9204-4ebf-bbe5-f505b01475bfo%40googlegroups.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+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/sphinx-users/a2d4e685-1353-4d51-809f-df42398c353bn%40googlegroups.com.