comparisons with java framework
igorlash
I'm java developer , and I like comparing web frameworks.
Members of django community talk a lot about easiness of django
especially comparing with java frameworks. But they have not compared
all aspects. And I want to compare one of them.
As user of good web framework I want to have documentation on my
computer and have possibility to read it offline.
Let's compare spring framework and django.
To get spring documentation I can download spring , and this zip file
contains apis , reference manuals (in PDF and HTML formats). Or I can
visit this page http://www.springsource.org/documentation and download
PDF or view HTML online (we will not take viewing HTML online into
account , I've mentioned about it only to be honest).
And now most interesting , let take a look at django. When you
download django you have documentation in ReStructured Text format
http://docs.djangoproject.com/en/dev/faq/general/#how-can-i-download-the-django-documentation-to-read-it-offline.
This format is not very readable so I've decided to convert it to html
or something other.
I was very surprised when I found makefile in the root of doc folder.
GREAT , to read documentation offline we need to install make.But not
all python developers , especially web developers know something about
make. Ok , I've installed make. But after that I found out I need to
install one more tool Sphinx But Sphinx requires some dependencies
and the easiest way to install them all is installing easy_install. Ok
I've installed easy_install and Sphinx but after that I've got error
about absence of some module (djangodocs).On this stage I gave up.
It's very interesting why I can't download django documentation in the
same way as I can download spring documentation or python
documentation (http://docs.python.org/download.html) ?
Russell Keith-Magee
If I have correctly interpreted you correctly, this was an
extraordinarily long-winded way to ask "Is there anywhere I can
download a PDF of the Django documentation, and if not, why not?"
No - we don't provide a PDF version of the documentation. This idea
has been proposed a few times in Django's history, but it has been
rejected in favour of providing the tools to let people build offline
versions by themselves.
Django's documentation is constantly improving, even for old versions.
Producing (and keeping up to date) PDF versions takes time. Yes, this
process could be automated, but building and maintaining the framework
to allow for automated documentation builds would take time.
Time is an extremely limited resource on any volunteer project, and
the core developers have made the decision that having an offline PDF
version of the docs is a lower priority to improving Django as a tool,
and improving the documentation that ships with Django and is
available as an online resource.
If you are having difficulties building the docs into a standalone
format, feel free to ask questions on this mailing list. We would also
welcome any suggestions for improvements to the documentation for this
process of building the documentation.
Yours,
Russ Magee %-)
igorlash
> extraordinarily long-winded way to ask "Is there anywhere I can
> download a PDF of the Django documentation, and if not, why not?"
> Time is an extremely limited resource on any volunteer project, and
> the core developers have made the decision that having an offline PDF
> version of the docs is a lower priority to improving Django as a tool,
> and improving the documentation that ships with Django and is
> available as an online resource.
documentation to make this project more attractive , I'm sure it
doesn't take a lot of time to generate it on configured environment.
But a lot of time can be saved on django users' side.More over it can
be critical on making decision between this or other framework.
On Feb 10, 1:09 pm, Russell Keith-Magee <freakboy3...@gmail.com>
wrote:
>
> > Hi everybody.
> > I'm java developer , and I like comparing web frameworks.
> > Members of django community talk a lot about easiness of django
> > especially comparing with java frameworks. But they have not compared
> > all aspects. And I want to compare one of them.
> > As user of good web framework I want to have documentation on my
> > computer and have possibility to read it offline.
> > Let's compare spring framework and django.
> > To get spring documentation I can download spring , and this zip file
> > contains apis , reference manuals (in PDF and HTML formats). Or I can
> > account , I've mentioned about it only to be honest).
>
> > And now most interesting , let take a look at django. When you
> > download django you have documentation in ReStructured Text format
Alex Gaynor
Alex
--
"I disapprove of what you say, but I will defend to the death your right to say it." --Voltaire
"The people's good is the highest law."--Cicero
Greg Ewing
> No - we don't provide a PDF version of the documentation. This idea
> has been proposed a few times in Django's history, but it has been
> rejected in favour of providing the tools to let people build offline
> versions by themselves.
What about an offline HTML version, then? If you're
already building HTML for online use, it can't be
much harder to provide a tarfile of it for people to
download.
--
Greg
Alex Gaynor
Greg Ewing
> As I said above, a checkout of the django source includes all the docs,
> which can be built into nice HTML just as online with the sphinx module
> for python. It takes all of 30 seconds.
Only if you have all the necessary tools and dependencies
installed and working, which not everybody does, especially
on Windows.
Besides which, you're *already* building the html yourself
for the web site, so why not make it easily available? Refusing
to do so seems pointlessly obstructive.
--
Greg
Alex Gaynor
These are just my thoughts, I'm not a core dev, but I'd rather they spent their time working on Django than remembering to rebuild the docs and fiddling with SVN post commit hooks.
Russell Keith-Magee
>
> Alex Gaynor wrote:
>
>> As I said above, a checkout of the django source includes all the docs,
>> which can be built into nice HTML just as online with the sphinx module
>> for python. It takes all of 30 seconds.
>
> Only if you have all the necessary tools and dependencies
> installed and working, which not everybody does, especially
> on Windows.
Well... there's your problem right there. :-)
> Besides which, you're *already* building the html yourself
> for the web site, so why not make it easily available? Refusing
> to do so seems pointlessly obstructive.
Yes. We want to make sure you never get any work done. We want to put
roadblocks on your road to world domination.
Seriously - dial down the rhetoric a bit. If you are unhappy with the
service you have received, we will happily give you a 100% refund of
your purchase price.
We already provide up-to-date generated HTML documenation. We just
don't provide it in a nice tarball to download. If you can't install
Sphinx and build the documentation yourself, then how about using wget
or any one of the several thousand site mirroring tools that are in
existence?
Building the infrastructure to handle automatic downloads is not a 0
effort activity. Someone needs to write the code, and someone needs to
maintain it.
Unfortunately (for you), in the opinion of the core developers, this
simply isn't worth the effort. While there is an occasional (and
usually very vocal) request for downloadable documentation, in our
estimation this is a very small group. We can spend our time trying to
satisfy this group, or we can spend our time improving Django - for
example, by adding aggregates and query expression to the ORM. We have
decided to do the latter.
Also - one of the benefits of using ReST as a source format is that it
is actually human readable. If you put the ducks in a row to use
Sphinx, and you can't find a site mirroring tool, you can still read
the raw ReST sources.
Yours,
Russ Magee %-)
Russell Keith-Magee
>
> The django community should allow to download html version of
> documentation to make this project more attractive , I'm sure it
> doesn't take a lot of time to generate it on configured environment.
You're sure, are you? Have you actually written the infrastructure to do this?
> But a lot of time can be saved on django users' side. More over it can
> be critical on making decision between this or other framework.
In your opinion. Personally, I doubt that any serious comparison
between Django and another framework hinges on the availability of a
downloadable documentation.
Let's break this down. We have finite resources, so you have a choice between:
1) Good documentation that is only available online
2) A slightly worse product, and slightly worse documentation that is
available as a downloadable package.
This sounds extreme, but it is the real situation. Any resources we
spend on building the tools to support an automated documentation
package are resources we don't spend working on Django itself.
You apparently would prefer option 2. That's your choice. However,
Django has decided to choose option 1.
If you feel that the availability of a downloadable documentation
package is a valuable resource, you are free to set up the
infrastructure to manage this process yourself. If you can provide
concrete evidence that there is a massive demand for this service, we
will obviously reconsider our opinion. In the meantime, we provide the
tools to enable you to build your own offline documentation.
Yours,
Russ Magee %-)
igorlash
Why do we need to use make ? Why this build can't be done without make
but only with python ? A lot of companies try to avoid using make and
moving projects to python as build tool.
On Feb 11, 1:59 am, Russell Keith-Magee <freakboy3...@gmail.com>
wrote:
Russell Keith-Magee
>
> Russ Magee , I've got a question personally to you.
> Why do we need to use make ? Why this build can't be done without make
> but only with python ? A lot of companies try to avoid using make and
> moving projects to python as build tool.
Make was used because it is suited to the task, is free, is widely
available, and is widely understood as a build tool.
Python, on the other hand, isn't a build tool. True - you can
construct a build tool using Python. However, Django isn't going to
put effort into making a new build tool when there is a perfectly
suitable existing alternative, and there isn't an existing pure Python
build system that has anywhere near the level of acceptance and
availability as make.
Unfortunately, saying "a lot of companies try to avoid using make"
doesn't make it true. I know many companies that use make when it is
appropriate, and none of them are looking to move to another option.
Even the Python project itself uses make.
Yours,
Russ Magee %-)
igorlash
only creating folders and running processes. So make isn't used as
real build tool in django.
> Make was used because it is suited to the task, is free, is widely
> available, and is widely understood as a build tool.
in C++ that's why I know something about make). I looks like decision
to use make was taken by C++ developer in past. So if this decision
were taken by java developer , every user of django would know ant.
Correct ?
> there isn't an existing pure Python
> build system that has anywhere near the level of acceptance and
> availability as make.
On Feb 11, 12:22 pm, Russell Keith-Magee <freakboy3...@gmail.com>
wrote:
Ales Zoulek
1] There are no HTML Doc to download on django site.
2] Nobody plans to work on in at the moment.
3] There is a way to generate the doc on user side.
4] If it's framework-selection criteria for someone, so django will not pass it.
Continuing in this discussion any further seems pointless.
A.
------------------------------------------------------
Ales Zoulek
+420 604 332 515
Jabber: ales....@gmail.com
------------------------------------------------------
Russell Keith-Magee
>
> But if you take a look at Makefile you will find that this file has
> only creating folders and running processes. So make isn't used as
> real build tool in django.
If this is what you believe, then you either don't understand what
make does, or you don't understand how to read make files. Either way,
I suggest doing some reading and experimentation.
>> Make was used because it is suited to the task, is free, is widely
>> available, and is widely understood as a build tool.
>
> Make is widely understood between C++ developers. (I used to develop
> in C++ that's why I know something about make). I looks like decision
> to use make was taken by C++ developer in past. So if this decision
> were taken by java developer , every user of django would know ant.
> Correct ?
Rubbish. Make is widely understood by anyone that has spent more than
30 minutes working with Unix, or has graduated from a CS course at any
halfway decent university.
Even if this wasn't true - you don't need to understand make files to
use them. If you're using a unix system, you won't even need to
install make - in all probability, it's already installed. Typing
'make html' really isn't that hard.
>> there isn't an existing pure Python
>> build system that has anywhere near the level of acceptance and
>> availability as make.
>
> http://www.scons.org/.
You are going to stand there and say, hand on your heart, that scons
has the same level of community acceptance and availability as make?
The core developers, myself included, aren't going to spend effort
rebuilding a build system that works _perfectly well_ right now, just
to satisfy your dislike of Make. Like it or not, Make works, it is
widely understood, and it's available everywhere. Even if Ant and
Scons were good tools, they simply aren't available as part of the
default OS install in the same way that make is.
I have no interest in going round and round discussing a decision
that, quite frankly, doesn't matter as much as you seem to think it
does. I've explained our reasoning, and explained our intentions.
Barring some stunning contribution, I'm going to stop responding to
this thread.
Yours,
Russ Magee %-)
Marinho Brandao
Andrew Ingram
> Rubbish. Make is widely understood by anyone that has spent more than
> 30 minutes working with Unix, or has graduated from a CS course at any
> halfway decent university.
>
> Even if this wasn't true - you don't need to understand make files to
> use them. If you're using a unix system, you won't even need to
> install make - in all probability, it's already installed. Typing
> 'make html' really isn't that hard.
I graduated less than 3 years ago with a masters in computer science
from a top uni for Comp Sci, and I never used make during that time
because everything we did was either in Java or in C that was so
trivial that a script wasn't needed.
Regardless of your opinion on using windows for development, such
developers exist (I use windows at work and osx at home). Not having
the time to develop a cross-platform build script for the docs is one
thing but it's pretty arrogant to dismiss it outright.
The Django devs are perfectly entitled to ignore Windows as far as
docs go, but please don't make assumptions about the abilities and
needs of your users.
Regards,
Andrew Ingram
Horst Gutmann
forces you to use `make` for building the documentation. Once you've
installed Sphinx, you also have `sphinx-build` on your $PATH::
$ cd $djangofolder/docs
$ sphinx-build . _build/html
-- Horst
Alex Gaynor
Andrew Ingram
> This is another case of generating work for someone as far as I can tell,
> sphinx autogenerates the make file for us, we didn't write it. To switch to
> some other system means to rewrite work that we didn't need to do
> originally.
>
> Alex
If this is the case then maybe all we need is better instructions on
building the documentation to be added to the Django site.
- Andrew Ingram
igorlash
> make does, or you don't understand how to read make files. Either way,
> I suggest doing some reading and experimentation.
make is and what make is used for.
Let's open make file which is located in django doc folder.
At the begging we initiate env variables which will be used later. Is
it magic which impossible to implement in python ?
Next we have some tasks and any of them doesn't do anything more that
just working with folders , showing help.and running processes.
If I've lost something magic in this script , just point me this
string.
To me it looks like you are fighting for your standpoint without any
common sense. You try to prove me that this is good because you like
it , Ok like it , if you want. I don't care
On Feb 11, 2:04 pm, Russell Keith-Magee <freakboy3...@gmail.com>
wrote:
Miguel Hernández
On Wed, Feb 11, 2009 at 1:43 PM, Andrew Ingram <an...@andrewingram.net> wrote:
> Regardless of your opinion on using windows for development, such
> developers exist (I use windows at work and osx at home). Not having
> the time to develop a cross-platform build script for the docs is one
> thing but it's pretty arrogant to dismiss it outright.
I've been developing django apps under windows xp for 2 or 3 years.
Have you tried:
C:\django\src\django-1.0.x\docs> c:\MinGW\bin\mingw32-make.exe html
It works for me under windows without a hitch, after easy_install
Sphinx, of course.
Bye
--
Obstacles are what you see when you take your eyes off the goal.
CLIFFORD ILKAY
> Russ Magee , I've got a question personally to you.
> Why do we need to use make ? Why this build can't be done without make
> but only with python ?
Who cares as long as "make html" works? Until you started this thread, I
had never built the docs. I have a full-time Internet connection so
accessing the web site for docs isn't a hardship for me. Curious what
all the fuss was about, I set off to build the docs. It took one
"easy_install Sphinx" to install the only dependency that I was missing.
Fifteen seconds later, I invoked "make html" and that ground away for a
few minutes while I did something else. To say this was a trivial effort
on my part would be an understatement. This shouldn't pose much of a
hurdle for a developer. Granted, I use an OS that doesn't treat me like
a serf working the land of my feudal overlord but even on the OS where
I'm made to feel that way, I had long since installed a build toolchain
for other things so I have "make" there too.
> A lot of companies try to avoid using make and
> moving projects to python as build tool.
If this is true, it is a clear case of missing the forest for the trees.
It would be quite silly to reject or accept Django based upon whether
the docs are built using "make" or some Python-based build tool.
This is an open source project. If you are so convinced that your way
would make the lives or many people easier, show your better way by
contributing code. If enough people see the merits of your way, they'll
adopt it and you'll have done a great service. There is no reason to
harangue Russ or anyone else about this. You have the power to change
things. Use it constructively.
--
Regards,
Clifford Ilkay
Dinamis
1419-3266 Yonge St.
Toronto, ON
Canada M4N 3P6
Russell Keith-Magee
Quoting from my very first reply to this thread:
"If you are having difficulties building the docs into a standalone
format, feel free to ask questions on this mailing list. We would also
welcome any suggestions for improvements to the documentation for this
process of building the documentation."
Yours,
Russ Magee %-)
denis
"... I need to install one more tool ... requires some
dependencies ..."
Avalanches can of course rumble rumble ... in installing or learning
anything at all,
not just Django. Two kinds of Avalanches:
a) what do I need to install ?
b) what do I need to know, e.g. basics of make ... ?
a) is helped by a project's doc and friendly attitude (Django ++),
plus the package installer: can it list dependencies, their
dependencies ...
before I start ? Too few packages have Avalanche alerts or even
reliable metadata --
fwiw only 230 of 5372 PyPI packages have "requires" in release_data.
b) is harder :~
Jan Claeys
Keith-Magee:
> Time is an extremely limited resource on any volunteer project,
And if you chase away potential volunteers that maybe want to implement
a certain feature, time will become an even more limited resource...
--
Jan Claeys