sphinx-doc / sphinxcontrib-django

This is a sphinx extension which improves the documentation of Django apps.
https://pypi.org/project/sphinxcontrib-django/
Apache License 2.0
43 stars 25 forks source link

Include role for models #19

Closed jmfederico closed 1 year ago

jmfederico commented 5 years ago

The Django admin documentation generator has a role to link to models :model:`app_label.ModelName` that links to the documentation page generate by Django.

This PR create the same role for Sphinx which converts the given model Django path (app_label.ModelName) to the real path of the class in python (app_label.models.ModelName), allowing for the same docstring format to be used by both the Django admin documentation and Sphinx and still generate valid links for both.

For instance, one can now refer to the auth User model like this (:model:`auth.User`) and it will link to django.contrib.auth.models.User if such class was included in the documentation.

jmfederico commented 5 years ago

I was not sure how to test the Role, so no tests were included 😥

codecov-io commented 5 years ago

Codecov Report

Merging #19 into master will increase coverage by 0.76%. The diff coverage is 75%.

Impacted file tree graph

@@            Coverage Diff            @@
##           master     #19      +/-   ##
=========================================
+ Coverage   57.84%   58.6%   +0.76%     
=========================================
  Files           6       6              
  Lines         204     215      +11     
=========================================
+ Hits          118     126       +8     
- Misses         86      89       +3
Impacted Files Coverage Δ
sphinxcontrib_django/roles.py 84.21% <75%> (-15.79%) :arrow_down:

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 5508cf0...3d581c3. Read the comment docs.

vdboor commented 5 years ago

Thanks for the PR so far! I like what you're working at! Did you get this to work in your own projects? I wondered, since I didn't see a py:model definition somewhere in the code.

The best test would be something like trying to render a small piece of ReStructuredText (e.g. that just renders :model:`auth.User` and proves it renders a proper link for that)