Update documentation to follow the documentation style guide

[asmeurer]

This issue should serve as a master issue for tracking which parts of the documentation follow the style guide that was developed as part of GSoD 2019 https://docs.sympy.org/latest/documentation-style-guide.html.

So far, following modules have been updated

• solvers (Copy Edit Solvers/Solvers for GSoD #17921)
• functions.special (Copy Edit Functions Special Submodule for GSoD #17844)

[Soumi7]

Will start working on implementing the style guide to functions.elementary.

[Soumi7]

@Sc0rpi0n101
I will implement the style guide for elementary submodule in functions, you suggested having the Parameters section before examples.

Should I then add the Parameters list before the examples when I add them here?

[Sc0rpi0n101]

I think we should finish the discussion regarding the Docstring sections and update the Documentation style guide before starting with the implementation.

Updating the docstrings now and then updating the guide later would require them to be changed later again. That would just be unnecessary extra work.
It would be better to change the required section order, add the missing sections, etc. in the style guide and change the docstrings as per the updated style guide.

[Soumi7]

@Sc0rpi0n101

Yes I think that too.

Then I will have to change the docstring sections in this documentation style guide first right?

https://github.com/sympy/sympy/blob/master/doc/src/documentation-style-guide.rst

[Soumi7]

This is my proposed flowchart of the docstring sections and their order. Suggestions are welcome!

[asmeurer]

These things were already discussed when we wrote the guide last year so we should stick with what the guide says now. If we want to change the guide we should start a new discussion, but it shouldn't block any work to update things to the current guide. Also any such discussion should reference the discussions from last year that lead to the current way things are.

[asmeurer]

Note that most of the discussions about this happened at #17715. I don't recall if we discuss this on that issue or in the private GSoD calls, but I do remember we explicitly chose to put examples up front.

[Soumi7]

As discussed before, I will stick to the latest guide for updating the docstrings. In #19613, I have added the same order in the docstring in the latest documentation style guide developed in GSoD 2019, but the rendering has produced slightly different results.

[asmeurer]

Regarding "returns", see also #17644

[Soumi7]

#19753

[asmeurer]

Adding a documentation page to the Sphinx docs is fairly straightfoward. If you look in the doc/ directory you can just mimic what is already there. However, it can sometimes be difficult because existing documentation can have build errors or formatting issues, which would have to be fixed.

[Soumi7]

Yes, will first make a list of all which are missing doc page by updating the comment, and then I will add the page to Sphinx docs.