I have created documentation for my project using sphinx. the current endpoint for my documentation is /. My question is, how can i make my documentation follow a docs/<filename> pattern?
EX. <app.url>/docs/index.html
in my project's config.py i have:
DOCS_DIRECTORY = '/docs/'
Add this line in conf.py：
html_baseurl = '/docs/'
ref: sphinx doc
you should call sphinx-build -b html sourcedir builddir. See the Sphinx doc, page First Steps with Sphinx
Related
I want to change my site using Hugo. I get stuck with modules. As per documentation (e.g. this theme) I just add theme = "github.com/nodejh/hugo-theme-mini" to the config file. It fails like this:
WARN ... found no layout file for "HTML" for kind "term": You should ...
if I perform hugo mod vendor the directory structure of the theme seems created in the _vendor dir, but there is not a single file inside. which explains the "not found" error in my eyes.
nothing (!) is rendered.
I also have this effect with a couple of other themes (I thinknoteworthy being one of them).
Set up a clean project
hugo new site testModules
cd testModules
and enable Hugo modules
hugo mod init randomName`
Paste the following lines in config.toml:
baseURL = "http://example.org/"
title = "Hugo Modules Test"
[module]
[[module.imports]]
path = "github.com/nodejh/hugo-theme-mini"
Start Hugo
hugo serve -D
Done!
The content of github.com/nodejh/hugo-theme-mini" will be downloaded and used as theme.
See the theme's documentation to add content
Optional:
hugo mod vendor
will make the content of the remote repo available in the _vendor folder.
(Surprisingly the content of exampleSite was not downloaded during the quick test I made)
I have two projects A and B, project A's docs are being hosted for different versions, so the doc urls have the format
http://example.org/A/1.0.0/+d/index.html
http://example.org/A/1.0.1/+d/index.html
http://example.org/A/1.2.3/+d/index.html
Project B depends on A's of specific version. In B's docs, I want to leave a link to A's docs like this:
"See also A's documentation (v 1.0.1)"
Is this possible to pass the version variable to the URL? I tried using rst_prolog:
conf.py:
rst_prolog = '''
.. |a-ver| replace:: {ver}
'''.format(
ver=meta.__a_dep_version__,
)
index.rst:
A's version: |a-ver| # this produces the correct output
See also `framework docs <http://example.com/A/|a-ver|/index.html>`_.
but getting the URL https://example.com/A/%7Ca-ver%7C/+d/index.html after doc building.
You can use the sphinx.ext.extlinks extension for this.
Example
Sphinx configuration
extlinks = {'docs': ('http://example.org/A/%s/+d/index.html', 'framework docs ')}
Your documentation
:docs:`1.0.1`
.. Result -> framework docs 1.0.1
:docs:`documentation (1.2.3) <1.2.3>`
.. Result -> documentation (1.2.3)
I am deploying my github blog using jekyll-bootstrap.I try to modify Rakefile to change the result of $rake post title="test" and then this command will generate a file named test.md（without date） in _posts directory,but unfortunately,when I run
$jekyll serve
locally,it seems that jekyll do not think test.md is an available post,what shoul I do?
I think that what you want it's custom url for your posts.
Leave alone the rake task, because the final post filename is generated in accordance with a permalinks pattern see permalinks documentation
By default you posts are generated following the default pattern /:categories/:year/:month/:day/:title/index.html
If you want to change this pattern, in your _config.yml, use permalink key :
permalink: /blog/:year/:month/:day/:title/filename.html
I want to create a link that refers to a section defined in another file.
I have found a similar question on "Python-Sphinx: Link to Section in external File" and I noticed there is an extension called "intersphinx".
So I tried this extension, but it doesn't work (Probably my usage is wrong).
I have tried the following.
conf.py
extensions = ['sphinx.ext.todo', 'sphinx.ext.intersphinx']
...
intersphinx_mapping = {'myproject': ('../build/html', None)}
foo.rst
...
****************
Install Bar
****************
Please refer :ref:`Bar Installation Instruction<myproject:bar_installation>`
I want to create a link like 'Bar Installation Instruction' with above markup.
bar.rst
...
**************************
Installation Instruction
**************************
.. _bar_installation:
some text...
When I run make html, I get the following warning and the link is not created.
foo.rst: WARNING: undefined label: myproject:bar_installation (if the link has no caption the label must precede a section header)
Thanks in advance.
Looks like it's not able to find your mapping inventory file. The first part of the tuple serves as the base URL for your links while the second part is the path to the inventory file. I believe the auto downloading of the inventory files (when you pass None) only works with URIs and not file paths.
In this example, I can build the documentation locally, but it will link to http://example.com/docs/bar.html
'myproject': (
'http://example.com/docs/',
'../html/objects.inv'
)
I'm using the Middleman Blog gem for my site, but by default it appears the blog articles need to be located in /source which isn't particularly nice when looking at the tree in vim and trying to locate one of the other files in there (a template for instance).
From looking at the documentation I can't see if there is any way of moving the blog articles so they are stored somewhere else such as a blog_articles folder or similar.
Is this possible?
Put the following in your config.rb file.
activate :blog do |blog|
blog.permalink = ":year-:month-:day-:title.html"
blog.sources = "blog_articles/:title.html"
end
Assuming you have a post 2012-01-01-example-article.html.markdown stored in the folder source/blog_articles.
You should now see the post with this URL: http://localhost:4567/2012-01-01-example-article.html. (You might have to restart middleman when changing the config.rb file.)
Please note that I also had to set blog.permalink, the blog.sources setting alone didn't do the trick.
A bonus tip: I have activate :directory_indexes in my config.rb file. This setting gives you nice looking URLs, without the .html part.
If you want the same for your blog posts you can drop the .html from your blog.permalinksetting. Like so:
activate :blog do |blog|
blog.permalink = ":year-:month-:day-:title"
blog.sources = "blog_articles/:title.html"
end
Now you can see your post with this URL: http://localhost:4567/2012-01-01-example-article.
I messed with the middleman-blog extension, but gave up for its relative opaqueness. In looking at the source, though, it appears the prefix option might do the trick for you? It's somewhat unclear whether the prefix is a URL prefix or a local path prefix:
activate :blog do |blog|
blog.prefix = "/blog_articles"
end
From looking at the code it transpires there is a :sources option which you can use. If you poke around in the source there is an example of this:
https://github.com/middleman/middleman-blog/tree/master/fixtures/article-dirs-app
The solution above worked for me when I made the following changes to the permalink / source config options:
blog.permalink = ":title.html"
blog.sources = "posts/:year-:month-:day-:title.html"
The permalink is the location which it will appear in the web browser url where the source is the locations of the posts.
Using middleman 3.2.1
I made blog folder inside source directory. Then i make posts directory and moved all my posts there. source/blog/posts/...
and then inside config.rb
activate :blog do |blog|
..........
blog.permalink = "blog/:year/:month/:day/:title.html"
blog.sources = "blog/posts/:year-:month-:day-:title.html"
.........
end