I'm new to Sphinx and having completed my documentation I noticed the search bar has disappeared when it was there previously.
I haven't (knowingly) changed anything in the conf.py file and am not sure why this has happened.
Does anybody know how to get it back?
You need to include
* :ref:`modindex`
In the file which will named ./index.rst
From the docs ...
The special document names (and pages generated for them) are:
genindex, modindex, search
These are used for the general index, the Python module index, and the
search page, respectively.
The general index is populated with entries from modules, all
index-generating object descriptions, and from index directives.
Related
I would like to create a tree from a markdown file using Python. From what I have researched, it seems that I can use Python's markdown module to do this.
For example by using this file: https://github.com/Python-Markdown/markdown/blob/master/markdown/treeprocessors.py
I am stuck because I am not sure how to access the modules which Python-Markdown have not quite exposed to end users.
Here is what I would like to do for an example Markdown file:
# Heading 1
## Heading 2
Line 1
- Bullet 1
- Bullet 1.1
I would like to be able to receive an output that has a structure something like this:
tree = process_markdown(markdown_text)
And tree[0].title can contain "# Heading 1" and tree[0].value can contain the entire markdown text inside of "# Heading 1" and including "#Heading 1".
Likewise, tree[0][0].title be equal to "## Heading 2".
Would ideally also be able to have a tree element represent "- Bullet 1" and the sub-bullet be included in the text in the value of that tree element.
I hope this makes sense. Now, I believe this can be obtained using the functions/classes in Python-Markdown but I am not able to figure out the syntax of those inside functions as to how to extract it.
Edit:
As I was researching further, stumbled upon the documentation for creating extensions for Python-Markdown. And in there is this reference to tree - https://python-markdown.github.io/extensions/api/#working_with_et. I can tell that this is what I think I need to figure out how to use, but still unable to because not able to figure out the syntax and how to use the related functions in Python-Markdown.
This question from 2014 is similar. The first answer there suggests Mistune, however, mistune does not seem to create the tree either.
I'm using the pywin32.client extension for python and building a Word document. I have tried a pretty good host of methods to generate a ToC but all have failed.
I think what I want to do is call the ActiveDocument object and create one with something like this example from the MSDN page:
Set myRange = ActiveDocument.Range(Start:=0, End:=0)
ActiveDocument.TablesOfContents.Add Range:=myRange, _
UseFields:=False, UseHeadingStyles:=True, _
LowerHeadingLevel:=3, _
UpperHeadingLevel:=1
Except in Python it would be something like:
wordObject.ActiveDocument.TableOfContents.Add(Range=???,UseFiles=False, UseHeadingStyles=True, LowerHeadingLevel=3, UpperHeadingLevel=1)
I've built everything so far using the 'Selection' object (example below) and wish to add this ToC after the first page break.
Here's a sample of what the document looks like:
objWord = win32com.client.Dispatch("Word.Application")
objDoc = objWord.Documents.Open('pathtotemplate.docx') #
objSel = objWord.Selection
#These seem to work but I don't know why...
objWord.ActiveDocument.Sections(1).Footers(1).PageNumbers.Add(1,True)
objWord.ActiveDocument.Sections(1).Footers(1).PageNumbers.NumberStyle = 57
objSel.Style = objWord.ActiveDocument.Styles("Heading 1")
objSel.TypeText("TITLE PAGE AND STUFF")
objSel.InsertParagraph()
objSel.TypeText("Some data or another"
objSel.TypeParagraph()
objWord.Selection.InsertBreak()
####INSERT TOC HERE####
Any help would be greatly appreciated! In a perfect world I'd use the default first option which is available from the Word GUI but that seems to point to a file and be harder to access (something about templates).
Thanks
Manually, edit your template in Word, add the ToC (which will be empty initially) any intro stuff, header/footers etc., then at where you want your text content inserted (i.e. after the ToC) put a uniquely named bookmark. Then in your code, create a new document based on the template (or open the template then save it to a different name), search for the bookmark and insert your content there. Save to a different filename.
This approach has all sorts of advantages - you can format your template in Word rather than by writing all the code details, and so you can very easily edit your template to update styles when someone says they want the Normal font to be bigger/smaller/pink you can do it just by editing the template. Make sure to use styles in your code and only apply formatting when it is specifically different from the default style.
Not sure how you make sure the ToC is actually generated, might be automatically updated on every save.
In my documentation I have an examples directory where I can say,
.. literalinclude:: examples/1_basic_usage.py
:language: python
:linenos:
..which works great, because they're code and they're formatted correctly as code.
However, I want to do a literalinclude on non-code documents. At the entire-project level I already have AUTHORS, DESCRIPTION, ATTRIBUTION, etc. defined, and I want to (essentially) paste them in-place but I don't know how.
Hopefully it's similar to this NON WORKING EXAMPLE:
Authors
-------
.. literalinclude:: ../../AUTHORS
Attribution
-----------
.. literalinclude:: ../../ATTRIBUTION
Apparently the way to do this is with the .. include:: <path> directive.
It's no-where obvious in their documentation and doesn't have an example stub at all.
Full documentation can be found in the docutils reStructuredText reference (#include).
The "include" directive reads a text file. The directive argument is the path to the file to be included, relative to the document containing the directive. Unless the options literal or code are given, the file is parsed in the current document's context at the point of the directive. For example:
This first example will be parsed at the document level, and can
thus contain any construct, including section headers.
.. include:: inclusion.txt
Back in the main document.
This second example will be parsed in a block quote context.
Therefore it may only contain body elements. It may not
contain section headers.
.. include:: inclusion.txt
I would like to print a list of all labels that are defined throughout all sphinx documents in my project including labels that I defined manually like this
.. _mylabel:
and also labels that sphinx generates automatically such as :ref:`genindex` and :ref:`search`.
For large projects I often forget how I spelled certain labels (Did I call it "examples", "Examples" or "sect-examples"?). If I could just print out all labels that are defined in any of the files, I could look at that list and recognize the name without checking the individual file each time I want to reference something.
When sphinx is running, it saves information about the documents that it parses in a file called environmment.pickle. This includes the labels of all references that are defined in the project, both explicit in the rst files and those set automatically when running sphinx.
This is sorted by domain. Here is the way in which I can find all labels in the "Standard Domain" (std):
import cPickle
dat = cPickle.load(file('environment.pickle'))
dat.domaindata['std']['labels'].keys()
This works equally well for other sphinx domains.
You will see that the label modindex (for the python module index) is always defined, even if the module index is not generated (Links to this will be dead).
Sphinx defines only very few labels (search, genindex, modindex), so the method stated here answers my original question, but is probably only useful for debugging of sphinx extensions.
The easiest way is to use grep and just search using a regex:
grep '^\.\. _' path/to/docs/* -r
I'm creating HTML from reST using the rst2html tool which comes with docutils. It seems that the code already assigns id attributes to the individual sections, which can be used as fragment identifiers in a URL, i.e. as anchors to jump to a specific part of the page. Those id values are based on the text of the section headline. When I change the wording of that headline, the identifier will change as well, rendering old URLs invalid.
Is there a way to specify the name to use as an identifier for a given section, so that I can edit the headline without invalidating links? Would there be a way if I were to call the docutils publisher myself, from my own script?
I don't think you can set an explicit id in reST sections, but I could be mistaken.
If you'd rather have numbered ids, which will depend on the ordering of the sections in the document tree, rather than their titles, you can do it with a small change to document.set_id() method in docutils/nodes.py (at line 997 on my version.)
Here is the patch:
def set_id(self, node, msgnode=None):
for id in node['ids']:
if id in self.ids and self.ids[id] is not node:
msg = self.reporter.severe('Duplicate ID: "%s".' % id)
if msgnode != None:
msgnode += msg
if not node['ids']:
- for name in node['names']:
- id = self.settings.id_prefix + make_id(name)
- if id and id not in self.ids:
- break
- else:
+ if True: #forcing numeric ids
id = ''
while not id or id in self.ids:
id = (self.settings.id_prefix +
self.settings.auto_id_prefix + str(self.id_start))
self.id_start += 1
node['ids'].append(id)
self.ids[id] = node
return id
I just tested it and it generates the section ids as id1, id2...
If you don't want to change this system-wide file, you can probably monkey-patch it from a custom rst2html command.
I'm not sure if I really understand your question.
You can create explicit hyperlink targets to arbitrary locations in your document which can be used to reference these locations independent of the implicit hyperlink targets created by docutils:
.. _my_rstfile:
------------------
This is my rstfile
------------------
.. _a-section:
First Chapter
-------------
This a link to a-section_ which is located in my_rstfile_.
As it seems that you want to create links between multiple rst files I would however advise to use Sphinx as it can handle references to arbitrary locations between different files and has some more advantages, like a toctree and theming. You can use sphinx not only for source code documentation, but for general text processing. Something like an example is the Sphinx documentation itself (there are hundreds of other examples on readthedocs).
Invoking Sphinx should be simple using sphinx-quickstart. You can simply add your exiting rst-files to the toctree in index.rst and run make html. If you want to document python code you can use sphinx-apidoc which will automatically generate an API documentation.
I made a Sphinx extension to solve this problem. The extension takes the preceding internal target and uses that as the section's ID. Example (from bmu's answer):
.. _a-section:
First Chapter
-------------
The permalink on "First Chapter" would point to #a-section instead of #first-chapter. If there's multiple, it'll take the last one.
Link to the extension: https://github.com/GeeTransit/sphinx-better-subsection