I know you can numerate parts of the doc using kind of dot notation. But is there a way to configure it somehow? I want three dots to stand for 1.1.a for example, not for 1.a.i. How can I do it?
As documented in section 21.2 of the asciidoctor user manual, you can use the following:
[arabic]
. food
[arabic]
.. fruit
[loweralpha]
... orange
... pear
... apple
.. vegetable
[loweralpha]
... carrot
... cabbage
.. meat
. drinks
[arabic]
.. juice
[loweralpha]
... orange
... pear
... apple
[loweralpha]
.. alcohol
[loweralpha]
... beer
... wine
You'll need to set the style after each dedent, hence it makes things a bit unwieldy.
I had hoped a simple stylesheet with overriding definitions (for example, for ol ol { list-style-type: "a" } could solve this, but it looks like Asciidoctor explicitly adds a class and type for each <ol> in the HTML output. The former could be changed (though inconveniently) with a user stylesheet, but I think the latter (type=) can't be overridden with a stylesheet.
Related
I'm experimenting with the Sphinx AutoAPI to make docs more maintainable. It's doing a great job, except for one thing: breadcrumbs.
Within the docs generated by AutoAPI, breadcrumbs don't work as I'd expect. Instead of adding a linked item at each depth, we get “Docs >> ”, followed by a single linked item.
This is a usability a problem, because you can’t navigate back up to a parent article after clicking into a child.
Note: I'm using the sphinx_rtd_theme, with a custom extrabody block for the header.
I haven't been able to find any documentation for the breadcrumbs in sphinx_rtd_theme.
Before diving into source code, I thought I'd ask if anyone else has seen/fixed this issue before. Thanks!
PS: You can see a draft PR for this work here: https://github.com/great-expectations/great_expectations/pull/1582
Thanks to Steve Piercy for a his helpful tip from the Pyramid project!
I added these lines at the end of my index.rst to activate breadcrumbs.
.. toctree::
:maxdepth: 2
autoapi/index
The breadcrumb links were still formatted like inline code, so I hacked my _static/style.css file like so:
ul.wy-breadcrumbs li code span.pre{
font-size: 16px;
font-family: HKGroteskPro, serif;
font-weight: 400;
color: rgb(155, 89, 182);
}
This styling isn't perfect, but close enough to not be jarring.
I have a quick question regarding implementation of a small change in our system, and I want to hear your opinion about my little disagreement with another developer in our company.
Our working environment:
Laravel
AdminLTE
Two laravel guards for 'partner' and 'staff'. Each type of user (partner/staff) has access to a different set of pages, using a different set of controllers and a different subdomain.
Admin LTE comes with some skins that you can apply to your <body>, for example 'skin-blue' theme. This is what our page looks like. Just for a comparison, if you remove the 'skin-blue' class, our website looks like this.
We were asked by our client to change the color of the top navbar for the Staff side. So, because the colors at the moment are being added by an adminLTE skin, I thought it was better to create a second theme for the staff side, calling it "skin-staff", and then in our base blade file, check for which guard is being used, and add the class accordingly.
<body class="#if(get_guard() === 'partner') skin-blue #else skin-staff #endif" ...>
I made a copy of the original skin-blue file, renamed it to skin-staff, and just changed the color of the necessary elements. I thought this was the best way to go about it, but the developer which had to review my github Pull Request said that because this was such a small change, it wasn't necessary to create a new skin. His proposed solution was to simply add the css classes in the blade file, something like:
<head>
…
<style type="text/css">
#if (get_guard() === 'staff')
.skin-blue .main-header .navbar{
background-color:#bdac3c
}
.skin-blue .main-header .navbar .sidebar-toggle:hover{
background-color:#ac9b2b
}
.skin-blue .main-header .logo{
background-color:#bdac3c;
}
… // and other classes
#endif
</style>
Now, to me this is not correct, because we are mixing the logic for staff and partner side without a clear way to differentiate them. If we use skins, we can simply say something like "The top navbar is yellow because we are using class skin-staff". And "We are using class skin-staff because we are on the Staff guard". The propositions are clear and simple. However, by adding raw CSS to our blade file, we end up with something like "The top navbar is yellow because we are using skin-blue and also we are on the Staff guard and also we have added some custom CSS for the Staff guard". The extra changes we introduce to the system don't follow the pattern used by adminLTE, to me they just look like noise. If we had to for example do this five more times, we would end up with a lot of CSS in our base blade file, which I think would look bad and would force us to eventually decide to use the skin system of adminLTE, something we could just do right away.
But, being as stubborn as I know I am, I don't know if I have the right idea or if I just want to do things my way.
What do you guys think? Is it better to create a new skin, even if most of the CSS code inside the skin file will be duplicated, but it allows us to stick to the existing way of doing things, or is it better to just add the code in the blade file and don't think more about it?
Thanks for your ideas
This is very much an opinion based question, there is no clear right or wrong answer here.
Personally, I agree with your coworker, why copy the whole theme, that is hundreds of lines long, just to change a handful of classes?
That said, I don't personally like the styles living in the DOM under a style tag.
Why not create a new CSS file that contains the styles:
.skin-blue .main-header .navbar{
background-color:#bdac3c
}
.skin-blue .main-header .navbar .sidebar-toggle:hover{
background-color:#ac9b2b
}
.skin-blue .main-header .logo{
background-color:#bdac3c;
}
… // and other classes
And then as long as you include this file after the base skin-blue CSS theme, your updated staff skin changes will take precedence.
Something like this:
<link rel="stylesheet" href="{{ asset('css/skin-blue.css') }}">
#if (get_guard() === 'staff')
<link rel="stylesheet" href="{{ asset('css/skin-staff.css') }}">
#endif
This keeps the abstraction of your CSS inside CSS files (and out of the DOM), yet only overwrites exactly what it needs to.
It also means that if you need to update a common style between the two themes, you don't need to make the change in two different files; you just need to modify the skin-blue.css file.
I am building documentation with Sphinx-RTD.
I want to have a link somewhere, and be styled as a verbatim or preformatted text.
For example, say I have this verbatim:
ALTER TABLE
Is there a way to link it somewhere, say a :ref:... or even just a standard hyperlink?
If I am not mistaken the "Replacement Text" directive can help.
As reStructuredText doesn't support nested inline markup, the only way to create a reference with styled text is to use substitutions with the "replace" directive:
I recommend you try |Python|_.
.. |Python| replace:: Python, *the* best language around
.. _Python: http://www.python.org/
So maybe something like this:
Click |altertable|_ to read details about |altertable|.
----
Blah blah blah
----
.. _altertable:
Here are the details about |altertable|: blah blah blah.
.. |altertable| replace:: ``ALTER TABLE``
There is a previous question that explains how to add a color span to some reStructuredText.
To recap the procedure:
First, you have the role.
.. role:: red
An example of using :red:`interpreted text`
It translates into as follows.
<p>An example of using <span class="red">interpreted text</span></p>
Now, you have the red class, you can use CSS for changing colors.
.red {
color:red;
}
How do you do this if you want text that spans multiple lines? For example:
.. role:: red
:red:`paragraph 1
paragraph 2
paragraph 3`
Where paragraph 1, 2, & 3 would all be "red". If I try to do this I get the warning message:
WARNING: Inline interpreted text or phrase reference start-string without end-string.
It doesn't create the span and inserts ":red:" into the text. It just doesn't interpret this as a string (as the warning suggests).
Basically, can this be done in reStructuredText, and if it can, how?
I'm using Sphinx 1.1.3.
There are a number of ways to do this, but one of them is to use the class directive:
.. class:: red
This is a paragraph.
This is another paragraph.
Most docutils HTML writers will put that into html output as a class html attribute, which you can then style with CSS.
In Sphinx, in particular, however, you may need to use rst-class instead of class in at least some cases. See: https://www.sphinx-doc.org/en/2.0/usage/restructuredtext/basics.html
Also, many block-level elements in RestructuredText take a :class: parameter which does pretty much the same thing.
Say my some.rst file looks like this:
============
My Title
============
1. Section
================
2. Section
=================
After compiling, in the resulting some.html there will be a table of contents in the side bar that appears as:
My Title
Section
Section
Is there a simple way to remove 'My Title' from the table of contents in some.html?
I was able to solve this by using the .. raw:: html method as described above, with a slight tweak (that avoided breaking the auto-generated TOC). as described earlier, if your file only contains .. raw:: html headings, it will break the Sphinx auto-generated TOC. however, if you use .. raw:: html and add --------------------- below it, it won't show on the left-hand nav, and won't break the TOC.
e.g.
so i finally accidentally figured out how to get headings to not be displayed in the left-hand TOC. if your file only contains .. raw:: html h2 headings, it will break the sphinx auto-generated TOC (as mentioned in the stackoverflow article). however, if you use .. raw:: html and --------------------- below it, it won't show on the left-hand nav, and won't break the TOC :star2:
e.g.
.. raw:: html
<h2>What Can I Do With KSQL?</h2>
---------------------
The easy way is to use an object type that's ignored by the TOC directive:
.. rubric:: My Title
This creates text that looks somewhat like a heading, but is excluded from the TOC. You can update your CSS file with whatever style you want for the .rubric class, even mimicking h1 style if you like.
See "Non-TOC headings within a Restructuredtext page" for how to define rubric styled classes.
If you are trying to remove it from all of your documents, try customizing the default template. Otherwise you will need to modify the HTML builder by creating a subclass.
Very late to this party, I know. I just had this issue, needed to mimic h2 and was not able to edit the style sheet.
My solution ended up being adding raw html in the some.rst:
:raw-html:`<h1>My Title</h1>`
1. Section
================
2. Section
=================
You can make your own h3 tag.
For your header you use:
|start-h3| My title |end-h3|
Later at the end of the file you write:
.. |start-h3| raw:: html
<h3>
.. |end-h3| raw:: html
</h3>
It seems you are talking about a local TOC (a "on this page" TOC). Unfortunately, Sphinx always prints a document title as first item (<li>). Actual local TOC (section titles) are all nested <ul> inside the first document title <li>. (Yes, it is annoying.)
You have two options:
If current Sphinx theme has local TOC, you have to tweak produced HTML markup. For example, by hiding document title using CSS. Copy-pasting from https://techwriter.documatt.com/2021/sphinx-localtoc-remove-document-title.html:
.localtoc > ul {
margin: 0;
}
.localtoc > ul > li {
list-style-type: none;
}
.localtoc > ul > li > a {
display: none;
}
.localtoc > ul > li > ul {
// any additional styles to local toc <ul>
}
Alternative might be to manually print local TOC, e.g. at the beginning of a document with the contents:: directive and its :local: option. Example taken from https://restructuredtext.documatt.com/element/contents.html#no-current-document-title:
#################################
Contents without a document title
#################################
Testing ``contents::`` directive with ``:local:`` flag.
.. contents::
:local:
**********
Section L2
**********
Section L3
==========