Include files in Sphinx output on any path - python

I have a project that I'm documenting where I've ended up with a structure like
docs/
conf.py
development/
architecture.rst
uimockups/
index.html
static/
<supporting css and js files>
mockup1/
index.html
ui1.html
ui2.html
mockup2/
index.html
ui1.html
ui2.html
Where everything under uimockups is just a static site. For organizational reasons I really want to keep the folder structure as is here, and would like to just copy uimockups to build/development/uimockups directly, that way I could link to it from my architecture.rst file.
I've searched around online, but most of what I can find is pertaining to the _static folder for customizing CSS and that sort of thing. All I want is to copy this entire folder to its corresponding location in the HTML build output. Is this possible without writing a custom extension? Can sphinx perform this simple task through configuration alone?

Well, I figured out a solution, but it isn't what I'd consider the best solution.
Since I wanted to be able to also do python -m http.server in the docs/development/uimockups folder and have it work, I ended up:
Renaming docs/development/uimockups/static to docs/development/uimockups/_static.
Changing all .html files to refer to files in ./_static or ../_static as appropriate instead of using an absolute /static path.
Adding 'development/uimockups' to the html_static_path variable in conf.py
This last step is the equivalent of adding cp development/uimockups/* $BUILD/_static/, so while not really ideal I end up with
$BUILD/
_static/
_static/ # From uimockups/
<supporting files>
index.html # From uimockups/
mockup1/
ui1.html
ui2.html
mockup2/
ui1.html
ui2.html
Then I can link to this with `link text </_static/index.html>`_ in my rst files.
I don't really like that I just have to shove this into the $BUILD/_static folder, and I can't just have it appear in $BUILD/development/uimockups instead, but this doesn't require me to write any code at least. It's definitely not scaleable though, if I had multiple "static sub-sites" then they would potentially step on each other's resources. One way to work around this would be to have
docs/
development/
uimockups-site/
uimockups/
index.html
mockup1/
mockup2/
_static/
And then add development/uimockups-site to my html_static_path list so that the output is
$BUILD/
_static/
uimockups/
index.html
mockup1/
mockup2/
_static/

You could add uimockups to html_extra_path in conf.py, and link to files in it as explained here.

Related

How To Render An HTML With Css + JavaScript File In Django

Hay,
I Have An HTML with Css + JavaScript Page When I Try Rendring This Page In Django Like This:
def about(request):
return render(request, 'about/index.html')
but I Only Get The Html Content Without The Css And JavaScript.
I Thought This Might Be Because Of The Statics.. So I Run:
python manage.py collectstatic
But I Get This:
0 static files copied to 'C:\Users\Ammar\Desktop\Python Learning\vidly\static', 128 unmodified.
What Should I Do,
I Wish Someone Can Help.
Django has a feature of managing a good directory structures
i.e. project->apps->templates/views/urls
In a Django project all static files example images,css files,(designing part) is stored in a directory named static.
This helps in leveraging the same static properties over several apps and keeping the code structure clean.
The collect static command helps to get all static files present in the project to a static folder and we need to mention the static path in settings.py file .
Django documentation might clear your doubts further I am putting link here that might help you .
https://docs.djangoproject.com/en/3.2/howto/static-files/
What's the point of Django's collectstatic?

Flask non-template HTML files included by Jinja

In my Flask application, I have one html file that holds some html and some js that semantically belongs together and cannot be used separately in a sensible way. I include this file in 2 of my html templates by using Jinja's {%include ... %}.
Now my first approach was to put this file in my templates folder. However, I never call render_template on this file, so it seems unapt to store it in that directory.
Another approach would be to put it into the static folder, since its content is indeed static. But then I don't know how to tell Jinja to look for it in a different directory, since all the files using Jinja are in the templates folder.
Is there a way to accomplish this with Jinja, or is there a better approach altogether?
You're over-thinking this. If it's included by Jinja, then it's a template file and belongs in the templates directory.

Using Sphinx to generate Python document using :glob:

I am new to Sphinx.
The file /home/user/myproject/docs/source/index.rst is as following:
My project contents:
.. toctree::
:glob:
*
I am getting the below message on running $ make html under /home/user/myproject/docs/:
checking consistency... /home/user/myproject/docs/source/design/index.rst:: WARNING: document isn't included in any toctree
What have I done wrongly? I would like Sphinx to automatically generate the structure depending on the directory hierarchy.
I don't think this is a supported operation.
Fortunately, it's not a very desirable one either, since you generally want the parts of your documentation to appear in a particular order.
If you are willing to just dump all your source files in source without a folder heirarchy, this is possible. Alternatively you could write a routine and run it from the Makefile before the call to sphinx-build.
As Mike alluded to, :glob: will just pull files in alphabetically by filename. See the docs here.
You can use “globbing” in toctree directives, by giving the glob flag option. All entries are then matched against the list of available documents, and matches are inserted into the list alphabetically.
If you want to use :glob: and maintain ordering with all your files in source, you'll need to prefix your .rst files with numbers.
Example
source
├── index.html
├── 1_intro.rst
├── 2_install.rst
└── 3_more-than-you-want-to-know.rst
Though, you will of course need to rename the files if you decide you want them ordered differently, rather than moving the order of an explicit list in index.rst.

How to have separate folders for each app's static files in Django

When I run python manage.py collectstatic, it puts all static files from different apps together in one location (STATIC_ROOT). I would like to have a separate folder within STATIC_ROOT for each app. For example static files from app1/static should go to STATIC_ROOT/app1 and static files from app2/static should go to STATIC_ROOT/app2. One way to do this would be to create another subfolder, i.e. app1/static/app1 - but I was wondering if there was a better way to do this.
I usually put them all in one directory like the following just like how I work with templates:
MyProject/staticfiles/app1
MyProject/staticfiles/app2
MyProject/staticfiles/app3

What's a good way to find relative paths in Google App Engine?

So I've done the trivial "warmup" apps with GAE. Now I'd like to build something with a more complex directory structure. Something along the lines of:
siteroot/
models/
controllers/
controller1/
controller2/
...
templates/
template1/
template2/
...
..etc. The controllers will be Python modules handling requests. They would then need to locate (Django-style) templates in associated folders. Most of the demo apps I've seen resolve template paths like this:
path = os.path.join(os.path.dirname(__file__), 'myPage.html')
...the __ file __ property resolves to the currently executing script. So, in my above example, if a Python script were running in controllers/controller1/, then the 'myPage.html' would resolve to that same directory -- controllers/controller1/myPage.html -- and I would rather cleanly separate my Python code and templates.
The solution I've hacked together feels... hacky:
base_paths = os.path.split(os.path.dirname(__file__))
template_dir = os.path.join(base_paths[0], "templates")
So, I'm just snipping off the last element of the path for the currently running script and appending the template directory to the new path. The other (non-GAE specific) solutions I've seen for resolving Python paths seem pretty heavyweight (such as splitting paths into lists and manipulating accordingly). Django seems to have an answer for this, but I'd rather stick to the GAE API, vs. creating a full Django app and modifying it for GAE.
I'm assuming anything hard-coded would be non-starter, since the apps live on Google's infinite server farm. So what's a better way?
You can't use relative paths, as Toni suggests, because you have no guarantee that the path from your working directory to your app's directory will remain the same.
The correct solution is to either use os.path.split, as you are, or to use something like:
path = os.path.join(os.path.dirname(__file__), '..', 'templates', 'myPage.html')
My usual approach is to generate a path to the template directory using the above method, and store it as a member of my controller object, and provide a "getTemplatePath" method that takes the provided filename and joins it with the basename.
The dirname function returns an absolute path, use relative paths. See what is the current directory when your controllers are executed with os.path.abspath(os.path.curdir) and build a path to the templates relative to that location (without the os.path.abspath part of course).
This will only work if the current directory is somewhere inside siteroot, else you could do something like this:
template_dir = os.path.join(os.path.dirname(__file__), os.path.pardir, "templates")

Categories

Resources