Go over Examples in builtins/files.py (File Operations)

[rocky]

Looking at Docs for the examples, is a bit unsatisfying.

Good examples should be mostly about the function described and have a minimum of setup or cleanup stuff that is not important for getting across the idea.

Examples to show off all the different kinds of error messages produced I don't think is important either, except in those cases where there is a common mistake that you want to point out. Users probably aren't inerested in all the different kinds of error messsages that an occur let alone all the different ways those errors can be triggered. This kind of stuff should be relegated to the pure test system and not the test + doc systems.

Something I just learned:

If you go into Django with make runserver you can work on the doc tests in the Python code and after seeing in the console terminal window that the server has been refreshed, you can see the changes to the docs pretty quickly.

This should be mentioned in docs somewhere.

[GarkGarcia]

This should be mentioned in docs somewhere.

Indeed, it should. However, I feel like this shouldn't be in the user-facing documentation, as regular users are probably not interested in this (I don't expect them to mess around the internals while using in web interface). This should be noted on the wiki.

@rocky and I were discussing this in our meeting yesterday. The user-facing documentation is filled with internal information, which is not relevant to regular users. This stuff should be moved to the wiki. @rocky Could you compile a list items of the documentation that should be moved to the wiki? I could help you moving this stuff if I know what needs to be moved.

[rocky]

The second section in Overview/Manual/Implementation/Documentation markup that starts ## comment talks about and describes tags like <dl>, ... isn't in the wiki yet.

Also I should mention that I added <i> for italic and the somewhat hacky fake imgpng (same as img) which can be used to import a PNG. (It wrks in the PDF too).

I didn't document the "Create Hash" button.

The section before, "Classes" , which is a diagram doesn't seem to appear in Django although it does appear in the PDF.

If there is a way to move that to the Wiki that'd be great.

With these sections incorporated into a wiki, then all of the "Implementation" section could just be some summary information about development with a link to the various parts of the wiki, much as the wiki home page serves right now.

Down the line, perhaps the various wiki sections could be removed and we could make just a developers guide in sphinx and put that on readthedocs.

[GarkGarcia]

The second section in Overview/Manual/Implementation/Documentation markup that starts ## comment talks about and describes tags like <dl>, ... isn't in the wiki yet.

Also I should mention that I added <i> for italic and the somewhat hacky fake imgpng (same as img) which can be used to import a PNG. (It wrks in the PDF too).

I didn't document the "Create Hash" button.

The section before, "Classes" , which is a diagram doesn't seem to appear in Django although it does appear in the PDF.

If there is a way to move that to the Wiki that'd be great.

With these sections incorporated into a wiki, then all of the "Implementation" section could just be some summary information about development with a link to the various parts of the wiki, much as the wiki home page serves right now.

Down the line, perhaps the various wiki sections could be removed and we could make just a developers guide in sphinx and put that on readthedocs.

Thanks! I'll try to work on this today.

[rocky]

I just noticed yesterday that there is an <em> tag which is basically the same thing as <i> that I added recently. But I don't think it hurts to have both.