I am using Sphinx to generate documentation for a Django project, and it is working really well. However it seems to be necessary to write the .rst files yourself, and once that is done, sphinx will compile the documentation from the docstrings when you run make HTML.
My questions is:
I am looking for the docs to reflect new additions to the project automatically without having to edit the .rst files manually.
As everything in Django always seems so simple, I find it odd that you have to create the rst files for the entire project manually, I would have thought that there is something that already exists, that automatically inspects the structure of the project, and builds the rst's from that.
I have looked at this project http://pypi.python.org/pypi/django-sphinx-autodoc/0.0 which looks promising, but I am surprised that there is not something more mature.
Since a while, Sphinx apidoc is bundled with Sphinx. This can create a full set of .rst files for you.
It becomes more of a problem if you want to document all the various django applications that you use in one site (this seems to be what you want). Sphinx apidoc wants a bunch of directories to scan for python packages.
Related
Im looking for a reasonably simple toolset and workflow for incorporating Sass into my Django projects. Im predominantly backend focused and have just started investigating Sass, so bear with me.
My initial idea was to keep things simple by just using node-sass without trying to incorporate Gulp, django-pipeline or anything else initially.
My Django apps are usually structured such that I create a static/app/css folder in each app. One option I guess would be to now create an additional folder per app for scss files, ie: static/app/scss. The problem there would be that when running collectstatic in production, the scss files will be gathered as well. So should the scss files for each app be kept somewhere else? (I guess it doesn't really matter if the scss files are included when collectstatic runs?)
Next, outside of my Django project folders I would create a folder to install node-sass since I wouldn't want to install it globally and I don't want the node-modules folder inside my Django project or inside source control.
I guess the node-modules folder can be thought of like using a python virtualenv instead of installing packages globally?
Next, inside my Django project somewhere (not sure where?) I would have the package.json file containing a scripts section for every scss file I want compiled to css, eg:
"scripts": {
"compile:sass": "node-sass app1/static/app1/scss/style.scss app1/static/app1/css/style.css",
"compile:sass": "node-sass app2/static/app2/scss/style.scss app2/static/app2/css/style.css",
"compile:sass": "node-sass app3/static/app3/scss/style.scss app3/static/app3/css/style.css"
}
Lastly, I would just run compile:sass with the watch flag to constantly compile any files I work on and put them in the correct folders.
So my questions are, is the above setup a good approach (at least initially if im not ready to add yet another tool like Gulp etc to the mix)?
Also, how will I run compile:sass considering my package.json file will be in the Django project somewhere and the node-modules folder containing the node-sass installation will be somewhere else.
I help maintain node-sass, so I won't say not to use it. There is an alternate libsass-python that you might want to look at if you're working with Python though.
Check out the django-sass-processor package. It's simple to configure and use. I've used it a few times and have had good experiences with it. The package abstracts away Gulp, so you don't have to worry about it and streamlines the whole process.
Here's a tutorial on how to integrate django-sass-processor into a Django project.
I'm trying to integrate the Famous libraries into an existing web application and the usage of requireJS with separate Famous JS files is giving me headaches. The existing web application does not use requireJS and it would be a big project to retrofit it to do so.
However, when I look at this demo:
http://demo.famo.us/tentacles/
A "famous.lib.js" file is included which encapsulates all the requireJS functionality into a single file.
How is this file generated? Does the Famous toolchain allow for creating this? If so, what is the command used?
The generator-famous docs say: "A single command to prepare your project for production". That may be what I'm looking for, but I'm not sure of the syntax for that command.
Does anyone know?
Yes. The single command is simply 'grunt'
Run 'grunt' in your application's directory and it will create a distribution folder called 'dist'
Inside 'dist' you will find everything compact and ready to go.
I have a package I want to install. I would like the files to end up in a different directory than the installation wizard choses for them.
For example, my Sitecore copy is running at C:\SiteCore\website
The module added files to C:\SiteCore\website\Console
I would like the files to ultimately live at C:\SiteCore\website\sitecore_modules\Console
I am using Sitecore 6.5 rev 111230, but we are planning to upgrade very soon. I would like for my installed packages to migrate seamlessly once we have upgraded. For reference, the package I want to install at the moment is the Sitecore Powershell Extensions. Although, I would prefer to apply a similar method to any future packages that I install.
Is there a secret switch in the package installation process to allow me to do this? Can I do it from the package installation wizard? Is there another way to install packages?
I'm assuming I can't just change the package path and expect everything to keep working. Do I have to update a configuration somewhere (a file or inside the Sitecore CMS GUI) to make the package recognize the new file locations?
The module creator defines where files exist. If you move them you run the risk of something not working. The best idea is to ask the creator on the Marketplace page of the module.
There is no turn-key way to change this.
I guess you cand take the code from MarketPlace and you can modify it.
I don't know how exactly is the licenses with MarketPlace modules, but I think people can modify others code.
Please check on code and also on items, maybe on some fields are values for folder path.
I discovered a way to accomplish this, but it can be quite involved or even impossible, depending on the complexity and size of the package.
First of all, I did take the question to the module creator and had a very helpful and informative conversation with the creator. So thanks for that suggestion - they may even move the install location in a future release, based on my request.
The workaround is to first install the package on a system as normal. Then you figure out everything that comes with the package. For files, this is easy if your Sitecore root is under source control. For items, this is really complicated. You can search for the installed items by owner, if you had the foresight to create & use a unique user for the package installation. Or you can check the untyped files in the package that are essentially xml based item manifests.
Once you have a detailed list, you make the desired modifications to the locations. Then you recreate the package yourself using the Sitecore package designer.
This works for simple packages - I did it to one small package that I hope to get up on the Sitecore marketplace as shared source soon. And by small, I mean it was 2 files and 3 items. The package that prompted me to ask this question would not cooperate with this workaround. The included .dll had some assumptions about the file structure hard-coded into it.
The workaround I took for the more complex package was really quite basic: I just created a new source-code external to the required path. That let me wrap everything up neatly without getting medieval on the package files.
Thanks for both your answers, a very fine +1 to you.
I'm a new developer on Django and I want to use some CoffeeScript in my dummy project. However, documentation about this topic isn't good and I want to know from the experts which is the best option.
I was looking at possibilities like compressor but it is still confused. I'd really appreciate some pieces of advice.
Thanks in advance.
For automatic compilation, there's django-coffeescript. For a more complete toolchain (a bit like Rails Sprockets) there's Gears, a stand-alone project with plugins for Django, Flask or compilation on the command line.
When I've used CoffeeScript with Django however, I've mostly preferred to set up compilation as a part of a build process (great to have one in any case), there I mostly used custom Paver scripts together with directory watching tools (like watchdog/kicker) to compile .coffee files to Javascript and putting them in my static directory.
What exactly is your question? Django will let you use any JS libary you want. Just add it your HTML pages or templates as you would do without Django.
If it is about serving of staticfiles, check this: https://docs.djangoproject.com/en/1.4/ref/contrib/staticfiles/
I use leiningen to manage my clojure project and I want to copy jar file along with some other files into a certain directory as a final part of a build process. Leiningen treats 'resources' as something which should be included into the jar file, and it is unacceptable for me. If I used maven, I could configure it for such task using maven-resource-plugin or fall back to Ant using maven-antrun-plugin, but leiningen is far more convenient tool for clojure projects.
Strangely, I couldn't manage to find anything about similar functionality in leiningen on the internet. This is curious, because one of major clojure applications is web sites, and web sites usually do not include their resources (js, css, etc) into the jar (or do they? That would be weird since slight css tweak will require rather lenghty recompilation). It comes naturally that we have to prepare site environment (copy static resources along with jar bundle into some directory layout), and this task should be done by the build tool.
Is there a plugin to copy files around the filesystem (or something which could substitute it, like running Ant), or I must write one myself? Right now I'm using shell scripts, but it is very inconvenient since I had to run several commands instead of one, and also it is unportable.
did you checkout lein-resource?
in any case. here is a long list of available plugins for lein, maybe you will fine some of them helpful