search

karimbahgat / PyCRS

Projection creation, and conversion to misc formats
MIT License
98 stars 20 forks source link

Settle on a standard docstring style #27

Open djhoese opened 5 years ago

djhoese commented 5 years ago

The docstring style used in this project is something I don't think I've seen before. A lot of python packages use either numpy style or google style docstrings (https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) which sphinx can parse automatically using the napoleon extension which is provided with sphinx in recent versions. There is also basic restructuredtext/docutils docstrings but please no. These styles and the tools that parse them sometimes provide additional features beyond just standardizing docstrings between packages. Would eventually switching to one of these standards be something you'd be interested in in the future?

karimbahgat commented 5 years ago

That's right, the docstrings used now are a bit custom/hybrid approach. I think I have intended it to be like google docstrings, but probably not consistently. I have also added things like markdown emphasis, because I don't actually use Sphinx, I instead use a lightweight one called pdoc, which parses the text as markdown and creates the html based on that. For an example of how these render see this older version of the PyCRS docs (https://pythonhosted.org/PyCRS/).

If we can standardize the docstrings to be more consistently like google style I would be happy with that. And if we can get away with just having basic markdown functionality and not any advanced linkages etc so that we could stick to pdoc, that would also be good.

But I'm happy to be convinced otherwise, discuss the pros and cons of using pdoc, etc. Actually, I'm pretty open to input and PRs on how to make the docs more stable/standardized, especially since pythonhosted.org no longer accepts new uploads, and we would have to change to something like GitHub site or ReadTheDocs. My experience with these are currently limited, so happy to accept help here, only guiding principle is that the workflow to update the docs/API should be simple/easy.

djhoese commented 5 years ago

Main pros to switching to sphinx besides all of the obvious linking and api docs functionality:

  1. Most other popular packages use it
  2. Use the intersphinx extension (built-in to sphinx) to link to other package's libraries and allow other libraries to link to pycrs documentation (methods, classes, sections, etc).
  3. Readthedocs can automatically build and serve the docs (I'm pretty sure I didn't have to do anything special to get this to work).

That said, I've never used pdoc so maybe it has its own benefits over sphinx. However, sphinx is pretty popular, stable, and flexible now so maybe it is time to look in to using it again? If collaboration is the goal having something that people are used to and uses restructuredtext could be good.

karimbahgat commented 5 years ago

Sounds good, I think I could go down that route. I think my main thing is that I need it to be easy to do, as I probably won't have time to get into learning the workflow of using Sphinx. So I'd be happy to accept PRs taking care of the transition to Sphinx, and if someone could create some developers note describing some easy steps of the workflow for updating and uploading docs in this Sphinx framework, or if someone is willing to be take care of the docs updating on their end, or even better if it can be automated maybe via Travis CI.

And if Sphinx can take google style docs, that would be good, but if you think it would be much preferable with restructuredtext, I trust your judgement and would be happy to accept PRs for that too. At the end of the day, whatever facilitates more usage and collaboration, without too much added complexity.

karimbahgat commented 5 years ago

I suspect switching to Sphinx might also be a solution for #24.

djhoese commented 5 years ago

The sphinx main documentation pages are written in restructuredtext, but the docstrings can be google/numpy/docutils/other. After you do the initial sphinx quickstart commands (I'll try to make a PR for this this weekend), it comes down to editing restructuredtext documents that can optionally link to the API docs in the docstrings. Readthedocs automatically builds what is in master so no need to do any special deployment unless the build process is complex (requires weird dependency libraries). At least I've never needed to do it in travis directly.

Edit: A lot of this is automated or comes down to a command that you run before every release as far as updating the API docs. Building the sphinx docs is just make html if you want to build it locally and see what they look like.