-
-
Notifications
You must be signed in to change notification settings - Fork 1.9k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Revamping the Documentation #1083
Comments
Thank you so much for looking into this @malefice ! If we're going to require contributors to write docstrings, I'd like to have some kind of CI checking the PRs. Maybe we can add |
So I already have some dirty proof of concept code for this one. In this PoC, I used the
Our custom docstring preprocessor will remove those lines from the docstring, generate samples based on those lines, and convert them into this which will be appended at the end of the docstring:
Notice that the third and fifth samples were automatically omitted because there are issues in the arguments lists. And the actual docs will look like this: The PoC generates samples using Anyway, your thoughts on this @fcurella? |
I'd rather avoid using .. example::
:arguments:
:result: 2092
.. example::
:arguments: min=123
:result: 8189 |
An alternative syntax could be: :sample: 2092
:sample min=123: 8189
:sample min=1 max=100: 49 |
I chose the I know The calls to
The To beef the validation up further, you cannot even do any other operation. You cannot perform arithmetic, slice a list, or even evaluate Anyway, in summary, given that (a) |
@malefice I'm ok with |
Yeah, the validator class will definitely have tests, and I am actually already done with that. I will let you be the judge once I make the PR, though this will probably be after the Python 2.7 EOL cleanup. With the EOL just around 5 days away, it does not make sense for me to write this with Python 2.7 compatibility in mind. |
In the current docs, each locale has links to every "provider category" module even if one has not been localized. Personal experience, I found it a bit confusing at first, since the current setup gives an impression that every "provider category" module has been localized for the listed locales. @fcurella would you prefer the localized "provider category" modules to be presented this way? In my opinion at least, it is a lot clearer which modules have been localized. |
@malefice I find your solution much cleaner too. Go for it! |
@fcurella I would like some feedback and suggestions regarding my work thus far before I proceed further. You can view the sample docs here, and if you want to see the preliminary (but not PoC dirty) code for this, you can view it here. There are a lot of methods that still do not have docstrings, and that is really the bulk of the work for this initiative, so to give you an idea of what every page should eventually look like, I finished the docstrings for the barcode provider methods which you can view here. |
@malefice I've checked the code on your branch, it looks really nice ✨! I don't really have anything I would change. LGTM 👍 |
Alright, so I will probably start writing some docstrings, but like I said earlier, I do not plan to make this Python 2.7 compatible since EOL is tomorrow. Shall we start tackling #1063? EDIT after 16 days: |
With the current way the provider method documentation is generated, the result lacks details and examples that will showcase the flexibility and capability of each provider method. I mentioned in #1074 about the idea of using
sphinx.ext.autodoc
to generate docs, and I already have some ideas on how to implement this, but I want to hear some thoughts and get some feedback.Since
build_docs
already traverse through eachProvider
class and its methods, we can changebuild_docs
to write something like this for each provider class. This will autogenerate docs from the individual docstrings (class level and method level). We can also usesphinx.ext.viewcode
to put links to the source code.As for sample code, we can probably use the
autodoc-process-docstring
hook to parse through examples in the docstring, and basically do whatbuild_docs
currently already does when generating dummy samples. The huge difference is that in this case, we should be able to write as many examples as we want, and let the docs building process evaluate and prettify the output. Of course, it is easier said than done, but I think it is well worth the effort that will solve all documentation woes.Of course if we go ahead with this style, we will need to write good docstrings for all existing provider methods, and we will also require contributors to write good docstrings moving forward. As for docstrings, we will also have to set a certain standard on how they should be written, e.g. reST vs Google vs numPy, and the format of the examples so we can write the parser.
Anyway thoughts and feedback?
The text was updated successfully, but these errors were encountered: