Code

Opened 7 years ago

Closed 7 years ago

#3341 closed (duplicate)

Man pages for executable scripts in django/bin/

Reported by: ubernostrum Owned by: jacob
Component: Documentation Version: master
Severity: Keywords: man documentation
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

I've been talking with people who maintain packages of Django for Linux distributions, and one concern that's come up is that they want to install the scripts from django/bin/ into systemwide locations like /usr/bin/, but doing so usually requires a man page; it'd make their lives easier if we could provide properly-formatted man pages documenting those scripts.

Attachments (2)

django-admin.1 (5.2 KB) - added by Marc Fargas <telenieko@…> 7 years ago.
django-admin manpage.
django-admin.2.1 (4.7 KB) - added by Paul <pb@…> 7 years ago.
revised django-admin.py manpage

Download all attachments as: .zip

Change History (19)

comment:1 Changed 7 years ago by Simon G. <dev@…>

  • Keywords man documentation added
  • Triage Stage changed from Unreviewed to Accepted

comment:2 Changed 7 years ago by Marc Fargas <telenieko@…>

I'm on with "django-admin.1" just in case someone is going to take a binary to write a manpage for. It's the first time I try to write a manpage so, please, be patient! ;)

Changed 7 years ago by Marc Fargas <telenieko@…>

django-admin manpage.

comment:3 Changed 7 years ago by Marc Fargas <telenieko@…>

  • Needs documentation set

Here's my first try to create a manpage! Just a few things to take into account:

  • The manpage assumes django-admin is installed as django-admin NOT django-admin-py.
  • The manpage has "Django developers" as it's author (see on the AUTHORS section), I set it that way as I think it's policy of the project to not set speciffic names.
  • Anyone has a spell-checker?

You can try the manpage by:

groff -man -Tascii django-admin.1

ubernostrum: I think this is the only binary which needs a manpage, or are the other files in bin/ installed on system directories? (compile-messages.py, daily_cleanup.py , django-admin.py, make-messages.py, unique-messages.py), if so, with those names or something like django-* ?

comment:4 Changed 7 years ago by Simon G. <dev@…>

  • Triage Stage changed from Accepted to Ready for checkin

comment:5 Changed 7 years ago by Marc Fargas <telenieko@…>

Note: When commiting this manpage do not close this ticket, Reference the changeset but leave the ticket open as ubernostrum asked to have manpages for everything in bin/ it's nice to go on adding the manpages as they get added but better leave the ticket open so we know there are more manpages needed!

thanks ;)

comment:6 Changed 7 years ago by mtredinnick

  • Patch needs improvement set
  • Triage Stage changed from Ready for checkin to Accepted

Okay, I finally got around to reading this. A few comments

  • Leave out the historical summary at the top. It's not normal man page practice. If you really want to put a capsule summary in, include a HISTORY section towards the end. Basically, everything under the "Django" subheading in the DESCRIPTION block should go, I think. Application manual pages do not generally do advocacy for the package they are part of and being consistent with the style of existing practice helps the user. You are writing the equivalent of, say, perldoc(1) here, not perl(1).
  • The sentence "And is released as Open Source" in the AUTHORS section has a few problems. It's not a full sentence, it should really be in the LICENSE section and it should mention the actual license (which is "the same terms as the Python license, see the LICENSE file in the documentation for details"). Open Source is too generic.
  • Rather than referring to any policy about not including authors' names, which reads a little oddy, just say "Originally developed at ...(blah-blah)... Refer to the AUTHORS file in the package documentation for contributors."
  • The program is called django-admin.py, the man page should reflect that. It is installed as django-admin.py. If Debian (for example) are going to change the installation name, they would be responsible for also patching the man page. Our shipped version of this document should match the name of the program as we ship and install it -- which means it has a .py extension.
  • It is quite okay (and recommended) to refer to the real documentation in a manual page like this. So listing all the options and then including something to say "full descriptions of all these options, with examples, can be found in blah-blah-blah" (or possibly putting that ahead of the options list) is fine.
  • Probably worth including an ENVIRONMENT section that mentions the DJANGO_SETTINGS_MODULE variable.

comment:7 follow-up: Changed 7 years ago by Paul <pb@…>

I'm attaching a revised version of the manpage file that attempts to address Malcom's concerns and includes some other miscellaneous cleanup.

Changed 7 years ago by Paul <pb@…>

revised django-admin.py manpage

comment:8 Changed 7 years ago by Simon G. <dev@…>

  • Patch needs improvement unset
  • Triage Stage changed from Accepted to Ready for checkin

comment:9 Changed 7 years ago by Simon G. <dev@…>

  • Needs documentation unset

comment:10 in reply to: ↑ 7 Changed 7 years ago by Marc Fargas <telenieko@…>

Replying to Paul <pb@e-scribe.com>:

I'm attaching a revised version of the manpage file that attempts to address Malcom's concerns and includes some other miscellaneous cleanup.

Thanks !

please: after check-in do not close this ticket, we still miss the rest of manpages! ;)

comment:11 Changed 7 years ago by mtredinnick

Great work, Paul. A couple of very small formatting issues, but this is pretty much perfect. I'll check it in.

Marc, leaving the ticket open is not a very neat workflow: there's no clear indication of which patches have been checked in and which are under consideration and which are ready to check-in. Trac sucks a lot in that respect.

I'll leave this open, but any new man pages should go in their own ticket and we can close this ticket once they've all been done.

comment:12 Changed 7 years ago by jacob

This looks great to me, but I'm not sure (a) where to put this in the tree (maybe under "extras"?) and (b) how to get it onto MANPATH from setup.py. Can someone who knows these things enlighten me so I can check this in?

comment:13 Changed 7 years ago by Marc Fargas <telenieko@…>

/manpages
/docs/manpages
would be nice, if not, extras ;)

dunno about the setup.py question.

comment:14 Changed 7 years ago by mtredinnick

Jacob: I was going to shove it under docs/man/ ("man" is more traditional than "manpages"). I got as far as checking that wouldn't screw up the automatic docs generation on the website (you were clever there; you put recurse=False on the filename searching in the docs code :-) ).

We're screwed as far as automatically installing into MANPATH. Python's distutils doesn't support this for reasons passing all comprehension. So we'd either have to do it manually -- which is officially hard to get right for all cases -- or (and this was my preferred path) just install it under the docs directory and let distros put it into place as part of their installation scripts (we can fix the rpm generation from bdist_rpm to do that).

comment:15 Changed 7 years ago by mtredinnick

(In [5457]) Added a man page for django-admin.py. Also install it correctly as part of the
auto-generated rpm. Thanks to Marc Fargas and Paul Bissex for writing the man
page. Refs #3341.

comment:16 Changed 7 years ago by mtredinnick

  • Triage Stage changed from Ready for checkin to Accepted

comment:17 Changed 7 years ago by Simon G. <dev@…>

  • Resolution set to duplicate
  • Status changed from new to closed

I'm closing this in favor of #5180 which supercedes it.

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.