We want to create a sphinx documentation for our MATLAB code. Usually the themes (alabaster, readthedocs, ...) provide a sidebar, a header, a footer, a search engine and so on.
If we integrate the sphinx documentation in MATLAB this does not look so well, because the MATLAB documentation already has theses things, so the sphinx pendants are redundand.
Is there a way to create HTML pages with sphinx without all this additional stuff?
I already looked for the topics 'sidebars' here https://www.sphinx-doc.org/en/master/theming.html for instance and here on stack overflow. But nearly all questions concerned how to add MORE bars, not to remove them.
I guessed i solved the problem at least for our needs.
To remove the breadcrumbs, the sidebar and the footer in the rdt theme one must really customize the css file, where theses things are defined. Unfolded, the css file is about 6000 lines of code, which we don't want to touch.
Instead i deformed the qthelp profile a little bit. The qthelp allows to specify an alternative theme with all the options needed for it:
qthelp_theme = 'classic'
qthelp_theme_options = {
# Basic
'nosidebar': True,
'body_max_width': 'None',
'rightsidebar': False,
'stickysidebar': False,
'collapsiblesidebar': False,
'externalrefs': False,
# Styling
'footerbgcolor': '#FFFFFF',
'footertextcolor': '#1A1A1A',
...
}
This results also in a 'naked' html page without the sidebar at least, which we can customize to look more like the rtd theme.
When building the documentation we can do it twice. The first run runs with
$ make html
and the second one with
$ make qthelp
The first is for the web representation of our documentation and the second one for the MATLAB help.
I guess we can live with this solution.
Related
I tried searching for this, but was unable to get any sort of answer that would be pointing to a solution. Let me start with some background first i suppose.
My Goal:
I'm currently figuring out how to get a decent automated documentation created for a certain python script repository. Its a library, so not a 'project' per se. It also lives in it's own place, as it's not maintained by a standalone python installation, but a Python 2.7 implementation that comes with Autodesk Maya.
As such, there's a bunch of modules in the library, organized the way it makes sense for us, and all functions have a docstring that is written according to the reStructuredText (:param parameterName: Description, etc..).
I was looking for something that would scrub through the whole repository, and create a nice html documentation that would look neat and make it easy to search for existing functions, thinking it must exist, but alas, i was unable to find anything that would be that user friendly.
What i tried:
Sphinx, pdoc3 - both proven various levels of not-idealness.
What i decide to do:
The last i tried is mkdocs. It seems fairly simplistic, not only because it doesnt actually do anything but create a stub of a page that gets filled based on one .yaml config file and per-page .md files that the user has to supply.
Now FYI, im new to both yaml and md, as i never had to use either.
I have decided to create myself a wrapper (for one-button-to-make-docs function) that would basically run through my python library, creating a .md page per module, and filling it with the functions/classes and their docstrings. I would have to parse the docstrings myself, but that's not that big a deal.
This would basically turn mkdocs into a pretty decent automated documentation with no needed manual input.
Now... I do like the theme readthedocs that you can set for your documentation in the yaml config file, but this is where i get stuck.
My Issue
When i 'mkdocs serve' my site, i'd like anything that has a hierarchy in the side menu, to be collapsible, like in this example (note the collapse/expand icons on the left sidebar):
But what I'm getting is no collapsability:
It should be noted, i suppose, that in my case, the 'attr' section is one .md site, that has just a simple structure of a h3 header per function name, and some description under, before having a horizontal rule to divide from the next function.
Also, in the yaml config file for the mydocs structure, the structure is kept very simple:
site_name: My Repo
nav:
- Home: 'index.md'
- 'Modules':
- attr: 'pageA.md'
- pageB: 'pageB.md'
- pageC: 'pageC.md'
- About: 'about.md'
theme:
name: readthedocs
include_homepage_in_sidebar: false
highlightjs: true
hijs_languages:
- python
markdown_extensions:
- toc:
permalink: True
separator: "_"
So the question is - how would i go about making my sidebar have little expand/collapse icons? (namely the attr site at this point)
Is it doable? Is it doable through the yaml config file, or the .md files of each page?
And potentially, is there a better alternative to what im doing, that wouldn't require me to write my own docs-making one-button solution?
Thank you!
Perhaps, you just need to write it differently. This is how it works in my project:
nav:
- 'index.md'
- 'glossary.md'
- 'Subject1':
- 'dir/file1.md'
- 'dir/file2.md'
- 'Subject2':
- 'NestedSubject2_1':
- 'dir/file1.md'
- 'dir/file2.md'
- 'NestedSubject2_2':
- 'dir/file.md'
- 'dir/file2.md'
- 'dir/file3.md'
- 'dir/file4.md'
And this is the least I can show, sorry. That's the structure my project has.
I have a python project that many of the functions and classes missing docstrings.
I know that PyCharm can automatically add docstrings by the Insert documentation string stub command using intention action. However, for large number of methods and functions, it is tedious.
Is there a method to bulk add docstrings to all the functions at once? then I will fill what is necessary manually.
If not in PyCharm, Is there any alternative client that can do it?
Thanks in advance for helps...
Finally, I found an answer, or may be a workaround
In pyCharm,
goto File\Settings\Code Style\Inspections then put a tick in front of 'Missing or empty docstring' Then press OK button.
goto Code\Inspect Code\ then select Custom scope>>Open Files
You will find a panel below with your project's name, then Python\Missing or empty docstring\
Right click on the title "Missing or empty docstring", and select the command {Apply fix 'Fix docstring'}
The program will automatically add docsrtings to all functions, and classes.
This works for me,
If anyone have better solution or workaround, so please share it with us.
Let say that I have open source project from which I would like to borrow some functionality. Can I get some sort of report generated during execution and/or interaction of this project?
Report should contain e.g.:
which functions has been called,
in which order,
which classes has been instantiated etc.?
Would be nice to have some graphic output for that... you know, if else tree and highlighted the executed branch etc.
I am mostly interested in python and C (perl would be fine too) but if there is any universal tool that cover multiple languages (or one tool per language) for that, it would be very nice.
PS: I am familiar with debuggers but I do not want to step every singe line of code and check if this is the correct instruction. I'm assuming that if functions/methods/classes etc. are properly named then one can get some hints about where to find desired piece of code. But only naming is not enough because you do not know (from brief overview of code) if hopefully looking function foo() does not require some data that was generated by obscure function bar() etc. For that reason I am looking for something that can visualize relations between running code.
PS: Do not know if this is question for SO or programmers.stackexchange. Feel free to move if you wish. PS: I've noticed that tags that I've used are not recommended but execution flow tracking is the best phrase to describe this process
Check out Ned Batchelder's coverage and perhaps the graphviz/dot library called pycallgraph. May not be exactly what you need and also (python-only) but in the ballpark.
Pycallgraph is actually likelier to be of interest because it shows the execution path, not just what codelines got executed. It only renders to PDF normally, but it wasn't too difficult to get it to do SVG instead (dot/graphviz supports svg and other formats, pycallgraph was hardcoding pdf rendering).
Neither will do exactly what you want but they are a start.
I'm using pelican in Python to generate the static pages. It is fine to use markdown with Pygment to highlight a code block, however when it comes to the inline highlight, there is a significant difference.
Please check my page. The page is in a dark background, but the inline highlight with the back ticks `` are white background.
The markdown code is
To clearify what exactly the command returns,
one can use `pack('>i', -2500).encode('hex')`{.python}.
Or I have a more complex solution like, `''.join(r'\x%02X'
% ord(ch) for ch in src)`{.python}.
So the question here is how to define the inline highlight style?
I tried to altered the pygments default.css file in the pelican theme, but it didn't work.
I found some related links:
Inline code syntax highlighting in GitHub markdown?
Inline code highlighting in reStructuredText
Pelican uses Python-Markdown with the CodeHilite Extension to pass code blocks to Pygments. Note that code blocks do not include inline code snippets. In fact I am not aware of any Markdown parser which supports highlighting inline code. Generally, inline code snippets are too short to effectively highlight and almost always too short to take advantage of Pygments' language guessing algorithm.
I see you have attempted to inform Markdown of the language using the Attribute List Extension. However, all that does is add a class to the HTML <code> tag that wraps the code snippet. As the CodeHilite Extension only works on blocks, it never even looks at it, and certainly never passes it to Pygments.
There are a few different options you have available (each increasing in the amount of work required):
You can write your own CSS which changes the background and text color so that they match the blocks. You won't get syntax highlighting, but the inline code snippets will at least match your theme. No need to define the language here.
You could use a JavaScript code highlighting library to highlight all the code snippets based on the language you define with the Attribute List Extension. However, this may require you to redefine the CSS for the JS library so it matches the output of Pygments.
You could write your own Python-Markdown extension (or perhaps fork CodeHilite) which also highlights inline code snippets in addition to blocks.
Personally, I would recommend (1) above. In fact, looking at your page, is appears that the code blocks have the following defined:
.highlight pre, .highlighttable pre {
background: #272822;
color: #f8f8f2;
}
That is, a <pre> element with a parent assigned the "highlight" class (or the "highlighttable" class) will be displayed with those colors. As you want the same colors assigned to inline code, add the following rule:
code {
background: #272822;
color: #f8f8f2;
}
Just be sure that you define that after the styles defined by the Pelican theme (which appears to be in http://vfxware.com/theme/css/bootstrap.slate.min.css).
Sure, you could alter the existing CSS, but then if you later decide to update to a newer version of the theme or change themes entirely, you might have to redefine your own rules. Therefore, I like to define my own set of overrides in a separate file which I always make sure is the last one loaded.
I've been bitten by this all too often. My problem was that I was using an older template's old pygment.css file while upgrading the Pygment modules (CSS didn't catch up with the Pygment plugin.
In my case, the older Pygment CSS was using an HTML tag class highlight when it should be using the newer codehilite class name that newer Pygment code is now using. (Thanks to Firefox->Windows->Web Developer->Toggle menu option for pointing out this "breakage".
Replacing the pygments.css CSS-style file does the trick in restoring this much needed code syntax highlighting capability.
To regenerate the pygments.css file, execute:
pygmentize -S default -f html -a .codehilite > pygments.css
or for a darker theme, use Pygmentize monokai style, as listed in pygmentize -L:
pygmentize -S monokai -f html -a .codehilite > pygments.css
Again, problem was that Pygments changed its HTTP tag class to a newer codehilite from an older highlight.
I'm creating simple comment-like application and need to convert normal urls into links, image links into images and yt/vimeo/etc. links into flash objects. E.g.:
http://foo.bar to http://foo.bar
http://foo.bar/image.gif to <img src="http://foo.bar/image.gif"/>
etc.
Of course i can write all of that by myself, but i think it's such obvious piece of code that somebody has already wrote it (maybe even with splitting text into paragraphs). I was googling for some time but couldn't find anything complex, just few snippets. Does filter (or something like that) exist?
Thanks!
PS. There is urlize but it works only for the first case.
Write a custom filter to handle all the necessary cases. Look at the source code for urlize to get started. You'll also need the urlize function from utils.
In your filter, first test for the first case and call urlize on that. Handle the second case and any other cases you may have.