I am using the Sphinx document generator to create documentation for one of my apps. When I search for some text that is in the documentation, it appears in the search results page, but the sub-section (----) in which it appears is not displayed in the search results. In examples online, the sub-section does display, e.g.,:
For me, only the main section displays:
I think that Sphinx does not index sub-sections. The example I showed, that has sub-sections in the search results, uses ReadTheDocs.
Related
I have a lot of ASCII docs at different locations and I want to create an index page which should render these documents. But the condition here is that I want to list all the document link on the index page and if the user clicks on any link then only the document should be displayed. I don't want to display the documents below the table of content. I just want to display the table of content on the index page.
Is there any way to do this?
If I understand you correctly, you wish to generate a multi-document website, but you want an index page that displays just the TOC, with the other documents served elsewhere. I believe the best way to get this effect would be to generate chunked XHTML output using the DocBook toolchain. I believe this should be possible with Asciidoctor tools, but I have only implemented this particular post-rendering toolchain with the original (Python-based) AsciiDoc rendering tool, as documented here. This setup is configurable to generate a TOC index page that links to chunked output (you can configure the level of chunking).
As you have already figured out, AsciiDoc's automated TOC generation only works on the present document, which requires including the subordinate document to get their headings for the TOC. I can think of ways to sort of game this, such as to include just the heading of the included document (include::path/to/document.adoc[lines=1]) and then hiding even those headings with CSS or something. The problem is, the links in the TOC will be pointing internally, so you'd need to handle that somehow.
Another way is to use any of the static-site generators that support or can be readily extended to support AsciiDoc. What you're talking about is not an out-of-the-box feature that I'm aware of, but they all at least make it possible to generate an organized TOC-type navigation.
I have just recently (yesterday) started using sphinx and read the docs for my project.
Till now I am happy with the Html documentation but the pdf version includes all the articles That appear in the index within the Contents heading. And the Documents orignal content/index is simply comprised of two links.
Please help.
The documentation is at http://todx.rtfd.io and the pdf is here.
When generating the PDF, Sphinx is always adding the content that is referenced via a .. toctree:: directive exactly where the directive is placed.
In contrast, when generating HTML, Sphinx is placing the content after the file that contains the toctree.
In this aspect, PDF generation and HTML generation are simply inconsistent.
Thus, you should place all content of the index page before the table of contents.
In case you want to provide an overview of the most important sections inline, you can use a list of references. Then, you might want to hide the toctree using the hidden property, for example like this:
Contents
--------
- :ref:`quickstart`
- :ref:`userguide`
Features
--------
- Fast
- Simple
- Inituitive
- Easy to Use
- Offline
- Open Source
.. toctree::
:hidden:
quickstart
userguide
Maybe it is just me, but I often have a hard time to understand and navigate
Sphinx based documentation, because the Table Of Contents only shows the
structure of the current page (in the standard themes at least).
There is also a previous and next, but what I really would like to see is
a TOC in the sidebar that shows all parts, with the current part expanded.
For example the main page (i.e. index.rst) would be 'Overview' and opened by
default. Introduction and Quickstart are Sections of index.rst:
Overview
Introduction
Quickstart
Credits
Tutorial
Contribute
Index
API
Search
'Tutorial' would be offered as next.
When the 'Contribute' item is selected, the TOC is updated like so:
Overview
Tutorial
Contribute
Install for development
Style Guide
Index
API
Search
Search, Index, API should link to the generated pages, that are typically
inserted like this in the Sphinx tutorials:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Is there a simple way to achieve this on Read the Docs,
or can anyone point to existing templates?
when I search in my private wiki for a word that it is located in different sections on the same page it only displays the first section where the word is located omitting the rest of the appearances
I am using cirrussearch 0.2 as my search engine for mediawiki 1.23.4
Any help will be appreciated
PV
You should probably try the fancy highlighter Wikimedia uses, found at https://git.wikimedia.org/project/search , and customise it for your snippet needs.
This question is related to this one
Tricks to Google for desired page quickly
Firefox can do some magic and bring exactly the required pages. E.g.
java 6 SimpleDateFormat
ruby doc rexml
But some times it fails giving a usual google results:
ruby rexml
And some times I whould like it to go to different a location:
javascript array slice
I see
http://www.w3schools.com/jsref/jsref_slice_array.asp
but whould like it to be
https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Global_Objects/Array/slice
How it works, btw? Where can I find all existing mappings, and how can I add/edit them? If they can be viewed/edited as text document, it whould be cool.
You can add YubNub as a search engine, (It's my default) and then your api docs of choice as a YubNub command if it doesn't exist already. I use it for Ruby all the time, e.g. rdoc String
You have several options:
Use the right-hand side search box where a search provider is available. MDC once had such a provider, but their search engine sucks big times. For example SO has such a provider. It's denoted by a shade of blue on the arrow right there.
Navigate to a particular search engine, right click the search field and "Add a Keyword for this Search". You may add "js" for example. In the future all you have to do is to type "js array slice" in the address bar and FF will bring you to the search results page of that particular search engine.
If there's no search engine on that site, use Google Custom Search, define engines as you like and then follow steps at point 2.
If you want to modify the built-in search engine for address bar, open a new tab, go to about:config and then search for "keyword.URL".
These aren't mappings, it's a Google Lucky search, isn't it?