I'd like to add a simple warning directive at the top of every page on a Sphinx RTD site:
.. attention::
The next major release of this project will launch on X date.
In the meantime, we're looking for feedback.
If you'd like an early preview, please reach out at someemail#someaddress.com!
What's the simplest way to do this? I'm using the sphinx_rtd_theme.
I can see how to add a block using the extrabody block, but it appears outside the main content area and is positioned and styled totally independently.
Ideally, I'd want this block to show up at an attention directive just below the breadcrumbs on every page.
You could add this to the conf.py Sphinx configuration file:
rst_prolog = """.. attention::
The next major release is imminent.
"""
and it will be included at the beginning of every source file that is read ‒ see https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_prolog.
F-string literals work too, so f'This is release #{release}' will substitute that variable value.
Related
I couldn't find a directive that handles this.
Suppose to have a single rst document and for some reason you want to hide a single section during the build (no matter if HTML, PDF..), like:
Visible section
===============
Here some example I want to show
Not visible section
===================
Some text that I have written but for the current build I want to hide from the final document
is there a .. hidden:: directive that handle this, I'm thinking of something like:
Visible section
================
Here some example I want to show
.. hidden::
Not visible section
===================
Some text that I have written but for the current build I want to hide from the final document
.. visible::
Another section
===============
Other visible section in both text and final document
You can use comment syntax: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#comments
The version of Sphinx I have got automatically generates an index.rst file that starts with a comment like this:
.. sphinx-quickstart on Sat Jun 22 15:48:19 2019.
You can adapt this file completely to your liking, etc
It does not show up in the documentation. You can start lines with two dots and a space followed by your own text and that does not show up either. You need to make sure that all the lines you create are indented the same as the first line. Then the whole section does not show up. Also make sure there is an empty line before the section and after it (unless it is the first section in the file or the last one)
Here is a solution to hide a section, so it doesn't show up in the HTML ouput.
However, this does not affect the build.
The idea is to use the class diretive and that way be able to assign a CSS class to the section(s). In CSS you can then define the class with display: none (or any other CSS).
For you example it would look like (note the identation):
Visible section
================
Here some example I want to show
.. class:: hidden
Not visible section
===================
Some text that I have written but for the current build I want to hide from the final document
Another section
===============
Other visible section in both text and final document
In your css you add the following styling:
.hidden { display: none }
Here is a link that explains how to add custom CSS to Sphinx.
I'm using the readthedocs theme for a personal sphinx documentation project. Everything works fine except the display of the left frame of the content list: It display all level of section headings, without showing any hierarchy. How to let it show levels as in most readthedocs documentation project?
After click the + sign, it looks right:
This is how I mark the section title:
Apache
======
How to restart
--------------
This sounds like this bug: Toc not expanding.
If not, please include your version of Sphinx, where you build the docs, and whether what you do to build the docs satisfies the conditions of that issue.
Otherwise, there is no configurable option to expand all options in the for the RTD Sphinx theme. See https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html#toc-options You will have to write custom JavaScript to make it so, and include the static asset with the theme. That homework is left to the questioner or a gracious answerer.
You could also file a feature request at https://github.com/rtfd/sphinx_rtd_theme/issues/new
This is the default behavior of sphinx. The section that you select expands on the left side bar. Else, it remains collapsed. https://docs.readthedocs.io/en/latest/versions.html this link also shows similar kind of behavior. To make it collapsible on clicking, you will require to update the theme.
I installed AsciiDoctor to generate html5-Websites from my ASCII-Doc files.
So far I did not find an option that generates a file like the one on e.g. http://www.asciidocfx.com/ or http://asciidoctor.org/docs/user-manual/ (i.e. (1) no footer with the date, (2) a menu on the left side and (3) linked headings.)
(How) Do I have to use templates for that?
I am not sure what you mean by "I have installed AsciiDoctor" are you using the Ruby version, the JavaScript version or the JVM Version (Ruby + JRuby)? How are you using Asciidoctor, directly from the command line or integrated in an other build system?
(1) I think (I am not sure about this one) that the footer is created if you have set the parameter docinfo1 to true. See Footer docinfo files.
(2) The menu on the left is called TOC (table of content), you might need add the parameter toc with the value left.
(3) The link on the headers are created when the parameter sectanchors has the value true. See the Anchors section.
I am having a little trouble here with a Magento installation here, which I "inherited" from a company who did some pretty heavy customizations to the theme.
I tried to rationalize most of the changes and was pretty successful with it. The problem is now, that I have some template files which have only one line of change.
In this specific case for example it would be a <button> that is now an <a> link. This is pretty much only one line in a 300 line template file.
Similar problems occurred with layout files of extensions. They have ONE dirty line in there, which for example resets the whole layout.
I then need to overwrite the complete layout XML file in the design, just to make a little change in one line, because those layout files are either overwritten or not. There is not merging process involved.
I took a look into the designer's documentation of Magento, but could not find anything useful.
I know that I could do some specific layout changes in the "local.xml" in my design, but those are more or less "contextless", which is not that great if those changes do belong to a certain extension.
Do you know a way to apply little template changes like mentioned in the first half or partially layout file overrides?
My main goal is to keep the files automatically updatable, which pretty much means: Download the module, replace files, done.
No manual updates to any overwritten files.
Use the "inherited" template as default template in a new package and add a child template with your changes. Example:
app/design/frontend/[package_name]/default - here will be the "inherited" old template
app/design/frontend/[package_name]/[your_child_template] - here will be your new child template
skin/design/frontend/[package_name]/default - here will be the "inherited" old template
skin/design/frontend/[package_name]/[your_child_template] - here will be your new child template
Partially layout file overwrides can be done for all pages or extensions in one local.xml file. Example:
app/design/frontend/[package_name]/[your_child_template]/layout/local.xml
If you want to add changes for a certain extension just add the extension xml file in your template folder. It will be the last one rendered and will wthe original. Example for the checkout cart page:
app/design/frontend/[package_name]/[your_child_template]/template/checkout/cart.phtml
For a small change inside a phtml file like your button example you will have to overwrite the whole phtml file. There is no way in Magneto to overwrite just a part of a phtml file.
there are tutorials on the web about gow to create index.html, css file and template.xml that contain placeholders. ok, i got it, it's simple. but i need a template that has some different views. for example:
-all pages have a topmenu, header, left sidebar, mainarea and a footer but:
-first page has no header .topmenu after which sidebar, mainarea and footer comes.
-second page has sidebar moved from left to right
-third page has four blocks (blocks for special offers) instead of mainarea.
as far as i can see, i need to create three standalone templates with unique set of placeholders for each template. because i can't see the way to change laarge mainarea placeholder with four placeholders for offers blocks on some pages. dynamically.
is there if-statements in joomla templates to simply determine a document id to view four placeholders instead of mainarea. or to not show header on the main page (f.e. doc. id="mainpage")
but i want it to be selectable like:
-this page has first case of that template (index_1.php)
-and that page has a second case of the same template (index_2.php)
like a selectbox.
is that possible?
I will make this an answer as opposed to a comment since I believe it will do what you are looking for.
Once your articles are setup and your links to them are established (the site has the info on it you're looking for), you can create the modules containing the data that you want shown from time to time.
Go to the module manager - on the right you should see 'module assignment' or something along the lines of 'display this module on the following pages'; you can then pick which pages you want the module to show on. You can specify all pages, none, specific pages, however you want.
This will enable you to show them only where needed however you like.
You can ALSO do this programatically inside the module (if you do custom HTML and use an extension like Sourcerer to add PHP to the module) with PHP should you want a little more flexibility, but just choosing the pages to show on should work for what you're doing.