I was not familiar with how to write docs for python source code last week, so I sent an email to my mentor, then got to know that docs mean more than the comments in the source. From reading the tutorial on http://docs.python.org/dev/ and the guide of Sphnix, I become more and more clear about the documenting stuff of Python. Therefore, I know that what I should do in following days is hacking corresponding .rst files in the /Doc directory. In the mean time, mentor also gave good suggestion on what kind of files would be modified towards my two tasks. With days’ reading the .rst file and generated docs in html format with browser, I know more about the Sphnix stuff, like ‘reStructuredText directives’ conception and can take my docs work more easier.
Towards the ‘develop’ command work, what I did is:
1) hacking the Doc/install/install.rst file to show usage of the ‘develop’ command
2) hacking the Lib/packaing/install.py to make ‘develop’ command be a kind of install command.
I mainly added several functions here to support ‘develop’, but I want to talk more here: if you have read the source code of install.py, you can know that there are three different ways you install a project, or we say there are three versions – _run_packaging_install, _run_setuptools_install, _run_distutils_install . The ‘develop’ command is a kind of install command, but it also looks like a much different and stand-alone stuff. So, there are also more than one versions to run the develop command – in my hacking source code, they are _run_packaging_develop and _run_setuptools_develop (no distutils version here). What’s more, there are some other counterpart of old functions in install.py to support ‘develop’ command, for example, _run_develop_from_dir, _run_develop_from_archive, etc.
One big problem here is also the naming of entrance of ‘develop’. We know that there is an
‘install_local_project’ function as the entrance to issue the ‘install’ command to install a project, then how the name of the entrance of ‘develop’ looks like. While, there already have been a lot of discussing, even arguing in the mailing list about this question. From my point of view and understanding of what people have said in the ML, I temporarily name this entrance function ‘install_editable’.
Towards the scripts work, what I did is:
1) removing old-style scripts support in Lib/packaging/command/build_scripts.py and just retaining the wrapper scripts support
2) doing necessary removing work in Lib/packaging/tests/test_command_build_scripts.py and fixing work against after this change
3) enhancing the docs strings of ‘build_scripts’ command, because it only support new-style scripts now
4) hacking corresponding .rst files in /Doc to complete the docs of new-style scripts
There is also a problem I think should be considered: after this change, we may destroy the old semantics of ‘scripts’. For the setup.cfg configuration file, scripts is an item of the ‘files’ section, which means ‘a list of scripts the project includes *optional *multi’. However, our new-style scripts do not exist – they are just generated after running the build_scripts command. If we fill kind of ‘foo=a.b.c.main’ dotted path strings which mean wrapper entries for future generation in the ‘scripts’ line, it looks strange – is the ‘foo=a.b.c.main’ a file?
I have sent an email to my mentor and am waiting for his reply. This is also a question we have talked in an early time, but I found that it maybe a problem to work around it.
The left work may be some docs work against the scripts.
The ‘pencils down’ date is approching, and I’m doing my best and hoping good luck.