Documentation overhaul

[JeS24]

🐞Problem

(Moved from #614)

We need help with the following with respect to the API documentation ("API reference") of the various EinsteinPy submodules:

1. Fixing grammatical errors and making the wording simpler at certain places.
2. Expanding the current documentation, something like what sunpy or astropy API references read like.
3. Adding new example Jupyter notebooks that serve as tutorials or improving old ones. (See also Add new example Jupyter notebooks / edit old ones #626).

Some good starting points are perhaps the docs for the following submodules:

• coordinates
• integrators
• metric
• symbolic
• geodesic

‼️ As the issue title suggests, this is a major reshuffle, which will likely require multiple people working on several pull requests. So, please feel free to work on any part of the docs and open Pull Requests, no matter the size of the contribution.

❕ Relevant information

• The source for the EinsteinPy docs can be found here: https://github.com/einsteinpy/einsteinpy/tree/main/docs/source/api, while the compiled docs are available at https://docs.einsteinpy.org/en/latest/api/index.html.
• If you want to know what the code does, a good place to start would be the source/examples/ folder, since it contains tutorials in the form of Jupyter notebooks. You can run the code there and understand what it is doing. You can then use that knowledge to improve the API docs (at least for the parts of the API present in the tutorials).
• We use reStructuredText (reST) for writing the docs in the numpydoc style. You can find a quick primer on reST here: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html, while an example of the numpydoc style is available here: https://numpydoc.readthedocs.io/en/latest/example.html.

📋Steps to solve the problem

Please consult the developer docs to setup your dev environment and get started. Also, feel free to communicate, if you hit a snag. You can do so in our Gitter or Matrix/Element chat rooms (recommended), or you can also reply here.

• Comment below about what you've started working on.
• Add, commit, push your changes
• Submit a pull request.
• Add this in the comments:
  • Addresses #<put issue number here> if you are partially fixing the issue.
  • Fixes #<put issue number here> if you are completely fixing the issue.
• Ask for a review in comments section of pull request
• Celebrate your contribution to this project 🎉

[Kennshen]

Hi, I am going to start working on the API documentation for the metrics submodule.

[JeS24]

Hi @Kennshen Sure. Please go ahead.

[Kennshen]

@JeS24 I have been trying to open EinsteinPy in editable mode, but when I follow the guide, I keep getting the following error message "./einsteinpy/[dev] is not a valid editable requirement. It should either be a path to a local project or a VCS URL (beginning with bzr+http, bzr+https, bzr+ssh, bzr+sftp, bzr+ftp, bzr+lp, bzr+file, git+http, git+https, git+ssh, git+git, git+file, hg+file, hg+http, hg+https, hg+ssh, hg+static-http, svn+ssh, svn+http, svn+https, svn+svn, svn+file)." Is there something I am missing?

[JeS24]

@Kennshen Can you share the command that led to that error, i.e. the command that you were using to install EPy in editable mode? It should be pip install -e ./einsteinpy/[dev]. The -e flag denotes editable and the [dev] marker signals pip to also install the developer dependencies. If the same error comes up, can you try the command without the [dev] marker?

[Kennshen]

I did try using the above method. I have also tried using the command without the [dev] marker and still got the same error

[JeS24]

@Kennshen I think, the path that you are giving to pip install -e is incorrect. Can you check if the folder structure looks like this, when you try to install it?

current_folder
└───einsteinpy

Where einsteinpy was created previously by git clone command, as in the guide. You need to be in current_folder and then type in the command, pip install -e ./einsteinpy/[dev], and it will work. Otherwise, navigate (cd) to the cloned einsteinpy folder and try pip install -e ./[dev].

[ghost]

I would suggest making a list of all modules that need to be documented. The list would contain whether they are open or not, competition status, and who is currently working on it.

This would also help people find modules that need documentation that are being worked on but not completed. More collaboration.

[JeS24]

@dishb That's a good suggestion. While the body of this issue has some of the modules listed and linked, there is no status tracking. Let me see, what I can do here; maybe leverage GitHub Projects.

[ghost]

@JeS24 - Github Projects sounds like a great idea! 😄

[Snerdify]

Hey has this issue been assigned or can I take it up? @JeS24 ?

[ghost]

There are many parts to this issue. I don't think one person can accomplish it.

[JeS24]

@Snerdify Feel free to contribute. As @dishb said, it is a large set of issues. However, for each individual portion that is overhauled, we will create different issues as a way of tracking progress. Meanwhile, let me see if I can set up GitHub projects. I might not have the right permissions on the repo.

[ghost]

@JeS24 I believe only maintainers with write access can create Projects. (Or collaborators)

[JeS24]

@JeS24 I believe only maintainers with write access can create Projects. (Or collaborators)

Yeah, in terms of GitHub roles, only maintainers can create Projects, it seems. Either way, for now, we can use separate issues depending on PRs to status-track.

[JeS24]

@dishb @Snerdify @Kennshen I have added this issue to a GitHub project here. If you are working on any of the components of this issue, please tell me. I'll create a corresponding issue and add you as an assignee to it on the project board. It will serve as the status tracker.

[JeS24]

Also, in case you cannot see the board publicly, give it some time. It will be up soon.

[GaganaMD]

Hey! I would like to be assigned to this issue.

[JeS24]

@GaganaMD Would you like to work on this issue or #650? Although, if you are working on #650, you can also improve the docs in coordinates simultaneously. At this time, updating docs for coordinates doesn't make sense, till either #644 or a similar PR is merged. But if you want to work on the docs for some other module in the list above, please mention it here and feel free to work on it.

[GaganaMD]

Oh. So can I start working on issue #650 first then, or should I wait?

[JeS24]

@GaganaMD You can start working on #650.