hello all experienced Sphinx users,
since a few days I'm performing my first experiences with Sphinx for building a small documentation site. I'm playing around using the Alabaster theme. When I try to place a logo in the left upper corner it only works with using an entry in the build configuration file 'conf.py' like this:
html_logo = '_static/images/PJS-small.png'
when I try to use the Alabaster theme configuration like this
html_theme_options = {
'logo': '_static/images/PJS-small.png',
'logo_name': True,
'description': 'one more logo'
}
no logo appears above the sidebar.
I'd like to use the theme configurations because I'm able to place a subtitle and other things like that.
Does anyone have an idea how to use the Alabaster configurations like it is documented?
Thank you very much for helping.
As per the Alabaster installation instructions,
you have to add an html_sidebars setting to the conf.py file:
html_sidebars = {
'**': [
'about.html',
'navigation.html',
'relations.html',
'searchbox.html',
'donate.html',
]
}
This causes Alabaster’s customized sidebar templates to be loaded.
Then you can specify the logo path like this:
html_theme_options = {
'logo': 'images/PJS-small.png',
# etc.
}
The path is automatically prepended with _static/.
In the theme configuration (theme.conf) file, you need to use the following syntax:
logo = images/PJS-small.png
logo_name = true
description = one more logo
Note the absence of the _static directory in the logo path (it is prepended in the theme's HTML template) and the lowercase boolean.
Still, you can set any theme configuration variable through the html_theme_options object in the Sphinx project configuration file (conf.py).
Related
I am using myst-parser and autoapi to generate the html page for my src folder. Everything is working fine, except I can't seem to find an option to change the labels on the left menu other than changing the html files manually.
I wonder if there is any option to write on the conf.py or index.md to set a different name for the documentation of my src folder.
As per image bellow, I just would like to change the name API Reference to something else.
This is how my conf.py file looks like
extensions = [
"myst_parser",
"autoapi.extension",
"sphinx.ext.napoleon",
"sphinx.ext.viewcode",
]
autoapi_dirs = ["../src"]
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
html_theme = 'sphinx_rtd_theme'
and this is how my index.md looks like:
{include} ../README.md
{toctree}
:maxdepth: 1
:hidden:
autoapi/index
Setup
I want to transfer data from my project to a TYPO3 instance. Assume I have an HTML export that generates about 20 different HTML files inside my TYPO3 directory. These files contain data from a different system and the data updates quite frequently, so I am overwriting them regularly with the newest information.
Problem
I would like to tell TYPO3 to load the HTML contents of each file as its own page. Please note: the pages are not complete html documents (no <html> or <body> tags). Instead, I want whatever code is in those files to be displayed inside the context of a TYPO3 page. Kind of like a TYPO3 HTML PageContent, but I want the source for the HTML to be from a file.
I don't care if I have to manually set up each page, but I haven't found any way to let a TYPO3 Page or PageContent get its data from a file. Do you know of any way this would be possible?
Note: iframe isn't a solution in my case. I am using TYPO3 7.6.23
My answer is based on the following assumptions:
You have you have a "frontend provider extension" EXT:yourext; if not you can change every path like EXT:yourext/Resources/Private/Etcetera with the proper ´fileadmin/etcetera/Resources/Private/Etcetera´
You use backend_layout on database to store the backend layout and use that field to control the frontend template. I don't remember if in version 7 you can also use the filesystem using key.data=pagelayout
of course you have to adjust the IDs of the backend_layout items
the files to include will be partials, stored in the folder EXT:yorext/Resources/Private/Partials/ and will be named
MyFileToIncludeOne.html
MyFileToIncludeTwo.html
et cetera
The basic TypoScript will be something like:
page.10 = FLUIDTEMPLATE
page.10{
templateName= TEXT
templateName.stdWrap {
cObject = CASE
cObject {
key.data = levelfield:-2,backend_layout_next_level,slide
key.override.field = backend_layout
//I assume you already have some templates
1 = TEXT
1.value = Default
2 = TEXT
2.value = Home
//The layouts for the "pages with html files" begin here
10 = TEXT
10.value = MyFileOne
11 =TEXT
11.value = MyFileTwo
}
}
layoutRootPaths {
0 = EXT:yourext/Resouces/Private/Layouts/Page/
}
partialRootPaths {
0 = EXT:yourext/Resouces/Private/Partials/Page/
}
templateRootPaths {
0 = EXT:yourext/Resouces/Private/Template/Page/
}
}
So, in the previous lines,
the template MyFileOne.html will include the partial MyFileToIncludeOne.html, with just writing in it:
<f:render partial="MyFileToIncludeOne"/>
You could also use distinct paths if you want to keep the files separated:
partialRootPaths {
0 = EXT:yourext/Resouces/Private/Partials/Page/
1 = fileadmin/some/other/path/
}
I hope I have not forgotten important passages. Feel free to ask for clarifications
I need to make a 4 column website with Bootstrap but in typo3 the default setting is to have 2 cols max. To be able to edit each column in backend I have created a layout following this tutorial: http://blog.sebastiaandejonge.com/articles/2012/july/26/implementing-typo3s-backend-layouts/
I cannot display content of the columns on frontend though.
In the template section for a page that uses this layout I have added
agptop1 < styles.content.get
agptop1.select.where = colPos = 20
agptop2 < styles.content.get
agptop2.select.where = colPos = 21
etc which are the positions set in the layout manager.
Now I should specify the variable like agptop1 so I created a template file among the other bootstrap templates in typo3conf\ext\bootstrap_package\Resources\Private\Templates\Page
It is a copy of the default template with some things changed like...
<f:layout name="Default"/>
<f:section name="Main">
<f:cObject typoscriptObjectPath="lib.dynamicContent" data="{pageUid: '{data.uid}', colPos: '3'}"/>
<div class="container">
<div class="row">
<div class="col-sm-3">
<f:cObject typoscriptObjectPath="lib.dynamicContent" data="{pageUid: '{data.uid}', colPos: '20'}"/>
<f:format.raw>{agptop1}</f:format.raw>
</div>
...like the line
<f:format.raw>
and the colPos. I suppose this is correct? I have found this somewhere here on SO.
But when I use this as a template directly in template editor of the page I need it for I only get blank page.
I cannot find out how are the default bootstrap templates linked to the Default.html and to manu configuration and how is this all linked to Backend Layout. I need to pick a backend layout, fill in the content, then something1 must tell something2 that I want to load standart page, standart menu but a specific template with the variables defined. How can this be done?
I'm sorry if it's too basic but it's my first day in typo3 and there is no manual for the new version.
The spaces on colPos = 20 are a problem in Typoscript. Using this should help:
agptop1.select.where = colPos=20
From your answer I assume, that your are using the plugin bootstrap_package. This plugin comes with some new predefined templates and you want to add one more, right?
Step 1 adding a new backendlayout
To add another option to your backend page-options, have a look into
BackendLayouts
Each file contains the description of one backend layout and each file is built the same way:
1. Defining a title (no need of using a language file here)
2. Defining the alignment (rows cols) of the content-container in the backend
3. Defining a icon
Just copy one of these files and modify it. These files have to be included in the page-layout and bootstrap_package does it automatically when it is installed. You can turn of this behaviour in the extension setting and include all backend layouts by your own. Therefor copy the file BackendLayouts.txt from bootstrap_package to your fileadmin, add your custom new layout and include the file in you pagets-config like so:
<INCLUDE_TYPOSCRIPT: source="FILE:fileadmin/template/typoscript/BackendLayouts.txt">
Note 1: For single files use 'FILE:' for Directories use 'DIR:'
Note 2: For pagets-config go to your root-page, edit it, got to resources and scroll down. Here it is. Enter code here.
If you have done it right you could now select your new layout from backend.
Step 2 Creating your own template
Copy one of the bootstrap_package template files and modify it, by only adding new cObject elements and what you need for your alignment.
<f:cObject typoscriptObjectPath="lib.dynamicContent" data="{pageUid: '{data.uid}', colPos: '2'}"/>
In addition copy the hole dir /typo3conf/ext/bootstrap_package/Resources/Private to the fileadmin and put your own template in the subdir 'Templates'
Step 3 Bring it together
As the last step you have to modify the typoscript-setup. I recommend to copy the bootstrap setup-files and include it manually rather then import it by static template.
So remove your static template "Boostrap Package (bootstrap_package)" copy the setup.txt and constant.txt from
/typo3conf/ext/bootstrap_package/Configuration/TypoScript/
to your fileadmin dir and include it like so:
Constants:
<INCLUDE_TYPOSCRIPT: source="FILE:fileadmin/template/typoscript/constants.txt">
Setup:
<INCLUDE_TYPOSCRIPT: source="FILE:fileadmin/template/typoscript/setup.txt">
After all you have to open your custom constant.txt file and add your own paths:
page {
...
fluidtemplate {
# cat=bootstrap package: advanced/100/100; type=string; label=Layout Root Path: Path to layouts
layoutRootPath = fileadmin/template/Private/Layouts/Page/
# cat=bootstrap package: advanced/100/110; type=string; label=Partial Root Path: Path to partials
partialRootPath = fileadmin/template/Private/Partials/Page/
# cat=bootstrap package: advanced/100/120; type=string; label=Template Root Path: Path to templates
templateRootPath = fileadmin/template/Private/Templates/Page/
}
...
}
And for the last step add your new template in the config.txt into the fluidtemplate-part 'page.10.templateName ...' doing some pattern-matching =)
10 = FLUIDTEMPLATE
10 {
templateName = TEXT
templateName.stdWrap.cObject = CASE
templateName.stdWrap.cObject {
key.data = levelfield:-1, backend_layout_next_level, slide
key.override.field = backend_layout
pagets__default_clean = TEXT
pagets__default_clean.value = DefaultClean
pagets__default_2_columns = TEXT
pagets__default_2_columns.value = Default2Columns
...
I hope, that i have described everything important. If you have trouble, have deep look into bootrack_package's source code. You can learn everything by miming what they have done.
Good luck
I am using 'Read the Docs' Sphinx theme for my documentation. In the original theme, given below
Read the Docs Sphinx Theme
the content or main layout width is designed to be mobile friendly. However, for my project I would like this to be a bit more wide. I do not know HTML and hence would appreciate if any one could give me some clues to increase the content (layout) width.
Another option is to create a stylesheet in source/_static with just the css you want, e.g.
.wy-nav-content {
max-width: none;
}
or
.wy-nav-content {
max-width: 1200px !important;
}
Make sure the directory is referenced in source/conf.py - I believe by default there's a line to do this, i.e.
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
Then create a custom layout in source/_templates/layout.html and do something like this to include your stylesheet
{% extends "!layout.html" %}
{% block extrahead %}
<link href="{{ pathto("_static/style.css", True) }}" rel="stylesheet" type="text/css">
{% endblock %}
Assuming you called your stylesheet style.css
In case someone is searching for a simpler answer...
combining the ideas from
https://samnicholls.net/2016/06/15/how-to-sphinx-readthedocs/
and the above suggestions, I found the easiest way of getting a custom window-width is the following:
In conf.py, add a function that adds a custom stylesheet:
def setup(app):
app.add_css_file('my_theme.css')
In conf.py, state/adjust:
html_static_path = ['_static']
Create a _static folder/directory if it doesn't exist.
Create a file called my_theme.css in the _static folder that contains the lines:
.wy-nav-content {
max-width: 1200px !important;
}
The HTML option added in Sphinx 1.8.0b1 (released Sep 2018) simplifies the process. The recommendation in Read The Docs Documentation is adding custom css to the theme via the html_css_files option in conf.py.
html_css_files = [
'custom.css',
]
Put the custom.css in the html static path folder (Default is _static folder).
Content of custom.css:
.wy-nav-content {
max-width: 75% !important;
}
First of all I must say, that during my sphinx quickstart I chose the option of separate folder for my sources and for my build.
It's a 3 steps process:
1. Create a document for your styles:
Where?
In the same directory where my conf.py lives, (in my case source), I created a folder for my custom static files (stylesheets, javascripts). I called it custom.
Inside it I created a subfolder for my stylesheets: source/custom/css.
In this subfolder I'm gonna create my custom styles: source/custom/css/my_theme.css.
2. Telling sphinx about it
Now we have to tell sphinx to spit this document inside build/_static/css, the same directory where is the stylesheet included in the Read The Documents theme. We do that adding the following line to conf.py:
html_static_path = ['custom'] # Directory for static files.
Done. Now, if we build, we will have the RTD styles (theme.css), and our custom my_theme.css in the same directory, build/_static/css.
3. Selecting our custom theme
Now we are gonna tell sphinx to use our custom my_theme.css, instead of the RTD one. We do that adding this line in conf.py:
html_style = 'css/my_theme.css' # Choosing my custom theme.
In our custom stylesheet, the first line should import the styles of theme.css with #import url("theme.css");.
And we are ready to start overwriting styles.
UPDATE: THERE IS AN EVEN SIMPLER WAY.
1. Put your customizations inside source/_static/css/my_theme.css.
In your custom stylesheet, the first line should import the styles of theme.css with #import url("theme.css");.
This way, you don't have to worry about messing up the default styles, if your custom stylesheet doesn't work, delete and start again.
2. Add the following line in conf.py:
html_style = 'css/my_theme.css'
The solutions here are somewhat hackish. If you want to include the style, and have a css override and have it work on RTD you will want something like this.
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if not on_rtd: # only import and set the theme if we're building docs locally
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
html_style = 'css/custom.css'
else:
html_context = {
'css_files': [
'https://media.readthedocs.org/css/sphinx_rtd_theme.css',
'https://media.readthedocs.org/css/readthedocs-doc-embed.css',
'_static/css/custom.css',
],
}
I have tested this myself and it appears to work locally and on RTD. Largely plagiarized from https://blog.deimos.fr/2014/10/02/sphinxdoc-and-readthedocs-theme-tricks-2/
source\conf.py
html_theme = 'sphinx_rtd_theme'
html_style = 'css/my_theme.css'
source\_static\css\my_theme.css
#import url("theme.css");
.wy-nav-content {
max-width: 90%;
}
That will be 90% width of your monitor.
I found myself repeating this customization on multiple projects I've worked on (based on the great answers here, of course 😃 ).
So I made an extension just for that, the usage is as follows:
pip install sphinx-rtd-size
And in the conf.py:
extensions = [
...
'sphinx_rtd_size',
]
sphinx_rtd_size_width = "90%"
Hoping this might simplify things for future users...
You can checkout the pypi page and the github repository.
For 'classic' Theme, The solution is as simple and as clean as :
# Add/Update "html_theme_options" like this on your conf.py
html_theme_options = {'body_max_width': '70%'}
Adapt the percentage to your taste.
Reference from sphinx: body_max_width (int or str): Maximal width of the document body. This can be an int, which is interpreted as pixels or a valid CSS dimension string such as ‘70em’ or ‘50%’. Use ‘none’ if you don’t want a width limit. Defaults may depend on the theme (often 800px).
To make the ReadTheDocs theme use the entire width of your screen you can modify the theme.css file, removing the max-width: 800px; property from the wy-nav-content class definition, like so:
.wy-nav-content {
padding: 1.618em 3.236em;
height: 100%;
/* max-width: 800px; */
margin: auto;
}
Some Notes
Source of theme.css is here:
https://github.com/rtfd/readthedocs.org/blob/master/media/css/sphinx_rtd_theme.css
On your filesystem it will be in (assuming you've run:pip install sphinx_rtd_theme):
lib/python2.7/site-packages/sphinx_rtd_theme/static/css/theme.css
To find the absolute path of theme.css on Linux/Mac you can run this on the command line (assuming you have set your $PYTHONPATH environment variable):
for p in `echo $PYTHONPATH | tr ":" "\n"`; do
find $p -type f -name 'theme.css' | grep sphinx_rtd_theme
done
The theme.css file will be minified so you can use a tool like http://unminify.com to make it easier to read.
The results:
Before:
After:
I would modify this in the css. You should search for the file theme.css (it is in the read-the-doc sources at "sphinx_rtd_theme/static/css/theme.css").
Make a copy of that file and put it in your sphinx _static dir. In that css file you can make all the layout changes that you need. (You might have to read a bit on css files if you have never worked with that.)
Hope this helps.
In pelican, by default, blog articles are listed on the index.html file.
What I want instead is that I use a static page as my home page and put all the blog articles on a dedicated "Blog" page.
How can I get this done?
While there are several possible methods for achieving your desired goals, I would start with the following changes to your settings file:
SITEURL = '/blog'
OUTPUT_PATH = 'output/blog'
PAGE_URL = '../{slug}.html'
PAGE_SAVE_AS = '../{slug}.html'
DISPLAY_PAGES_ON_MENU = False
DISPLAY_CATEGORIES_ON_MENU = False
MENUITEMS = [('Home', '/'), ('Blog', '/blog/')]
Put your blog posts in content/ as usual, and then create your home page with the following headers and save as content/pages/home.md:
Title: Home
URL: ../
Save_as: ../index.html
This is the home page.
Caveats:
Dynamic navigation menu generation has been effectively turned off since it doesn't work well with this configuration. Highlighting for the currently-active menu item — a feature you normally get out-of-the-box — will not be present in this configuration and, if desired, must be implemented separately in your theme.
If your theme's base.html template has a link to your site home that depends on SITEURL (e.g., as the notmyidea theme does), you will need to change the link to point to <a href="/"> instead.
Set the following in the pelicanconf
DIRECT_TEMPLATES = ['blog']
PAGINATED_DIRECT_TEMPLATES = ['blog']
1st line will set blog.html for the articles
2nd line will allow pagination of blog.html file
For the index page, create a pages folder in the content directory and create the .md file there and set save_as:index.html this will save the md file as index.html
This is covered in the Pelican FAQ
- "How can I override the generated URL of a specific page or article?"
Basically, in your contents folder, create two subfolders:
/contents/blogs, which will store all your blog entries
/content/pages, which will store your other static pages (including your home page)
In the pages subfolder, create a file (e.g. home.rst) with the option :save_as: index.html, which will make this file your home page. E.g.:
Home
####
:date: 2015-05-22 12:30
:url:
:save_as: index.html
This is my home page
In your pelicanconf.py file, specify the following options:
DISPLAY_PAGES_ON_MENU = False
DISPLAY_CATEGORIES_ON_MENU = True
USE_FOLDER_AS_CATEGORY = True
PATH = 'content'
ARTICLE_PATHS = ['articles',]
PAGE_PATHS = ['pages',]
MENUITEMS = ()
You should now have a home page and a contents bar with a Blogs menu.
If you want to add more menus to the contents bar (for example an About or CV menu), create the corresponding files in your pages folder, and add them to MENUITEMS:
MENUITEMS = (
('About', '/pages/about.html'),
('CV', '/pages/cv.html'),
)
I have an answer similar to the one Justin Mayer gave, except in mine I change blog article urls instead of page urls.
I've been getting the following error when trying to use the answer above, so it might be useful to other people having the same issue
ERROR: Skipping volunteering.rst: file '../volunteering.html' would be written outside output path
ERROR: Skipping presentations.rst: file '../presentations.html' would be written outside output path
Make all article urls to be under 'blog/' url
ARTICLE_URL = "blog/{date:%Y}-{date:%m}-{date:%d}-{slug}.html"
ARTICLE_SAVE_AS = "blog/{date:%Y}-{date:%m}-{date:%d}-{slug}.html"
Put blog index under 'blog/' url
INDEX_SAVE_AS = "blog/index.html"
Add a explicit menu item for blog index
MENUITEMS = [
('home', '/'),
('blog', '/blog'),
]
As your page is now an index page, automatically displaying link to that page in the menu will lead to a broken link, so you will have to set the following option and specify the following flag
DISPLAY_PAGES_ON_MENU = False
For the new index page, add a directive save_as, like Justin Mayer pointed it out. Here how it looks in rst
About
=====
:slug: about
:category: About
:save_as: index.html
This should give you a home page and an index page for articles.
When you want to add more static pages, you will also need to add them in menu items that still contains '/pages' prefix in the url if you want links to the pages appear in a menu. i.e for the volunteering.rst with the following content,
Volunteering
============
:slug: about
:category: About
Your MENUITEMS variable will look like the following
MENUITEMS = [
('home', '/'),
('blog', '/blog'),
('volunteering', '/pages/volunteering'),
]
I tested this answer on pelican 4.2.0.
You can use the following settings to put the index file for example at /blog/index.html.
INDEX_SAVE_AS = 'blog/index.html'
INDEX_URL = 'blog/'
Then you created a home.md page and use "save_as: index.html" directive for the actual home page.