Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
308 documentation #312
I'm not finished and have more things I'd like to do to make it better, but I'd like to get some feedback. If you'd like to see what the documentation looks like currently, I've attached a zip file of the build, just run the index.html in your browser.
It's not perfect, I'm still working on a few things, but it's got full API generation, and the Wiki is completely migrated over. I'd like to know your thoughts before getting too far along. I'd say it's around 90% finished, though. :)
I've still got to do things like:
Additionally, in the commits, I've written in-depth descriptions so if you have any questions as to 'why', hopefully they're answered there and if not, let me know if you have more questions.
It'll probably be a couple of days before I get back to this, so take your time with feedback. I probably won't hit it again until Saturday or Sunday.
Additionally, it's going to fail right now. I have no clue why, because in my Travis build history, every commit up until the last two were fine. My initial guess is that the flake8 settings in the tox.ini file are interfering with what Travis sees, but I'll look into that whenever I get back to working on this this weekend.
Cool! So it looks like you ported the wiki documents into the docs tree for the read the docs stuff very cool. Some dumb questions - the tox file, is that meant to replace the travis file? Just wondering how that fits into the puzzle. Or does it replace the make or setup.py files?
It does not replace the setup.py file.
It would not replace the travis file either, but the travis file would call the tox file, with a prerequisite of the travis file running
It would move the steps from the make file to the tox file, as individual steps which can also be run in sequence like here
Additionally, there will be a deploy step for the documentation as well (in the travis file) that will upload the built documentation to readthedocs, on a release.
Edit: Whoops, hit the wrong hot keys, didn't mean to close it.
I need to fix whatever is happening with the flake8 errors that are happening, as I don't see them when running locally. I'll also check and see if the documentation is finished, I did another pass this weekend with formatting updates. Are there any changes that you would like to see? Stuff like link formatting and table formatting should have been fixed already in commit 0bd50b0
I didn't know that it would take the opentimelineio url whenever I was connecting the accounts, so I'll see if deleting it will get rid of the usage on RTD. I think it would.
Basically, you just have to connect the Github account and import the project.
Also, after a bit of work and research, I got the api documentation building for readthedocs, which is not out of the box behavior for RTD. That's everything in ab8d3c2
@@ Coverage Diff @@ ## master #312 +/- ## =========================================== - Coverage 90.89% 73.76% -17.13% =========================================== Files 53 59 +6 Lines 4512 5341 +829 =========================================== - Hits 4101 3940 -161 - Misses 411 1401 +990
This should be finished. Coverage percentage dropped, because if you look here, you can see that it's picking up new files that the make was not picking up before. I do not know why.
I have currently left the makefile as-is (minus updates for pep8 being renamed to pycodestyle) in order to give people time to transition. I'm more in favor of clearing out the make file, but realize that some people may want to maintain what they may be used to.
With that, I recommend closing the wiki with this change. I have also updated the README to point to the documentation url.
Install tox into your local virtualenv that you're using with
This will run all of the steps listed in the tox file underneath the
To run specific steps, like building the documentation locally, run
This will output the documentation to
In the tox
Coverage is built automatically in the testenv step. It has dropped from 90% to 72% because it's picking up new files that it was not picking up before. I didn't see a way that it was omitting those files, and they don't appear to be new files, so I'm not sure why it's picking those up now.
There is a tox step called dist which builds the zip file for you.
The manifest was added to ensure that what is being added to the distribution that gets packaged is what is expected. You can adjust it by editing the MANIFEST.in file. I chose to omit tests, examples, documentation, PDFs, and dotfiles.
If you look in the check-manifest line, you'll see an
Feel free to ask any questions you may have.
After some discussion internally and with a few other contributors, we are mostly in agreement about this PR. The new docs look really great and this will be much better than the wiki. Thanks for putting so much effort into this.
The only outstanding concern is replacing Make with tox. We are moving towards the C++ API also, so we will need to add CMake to the mix later. Since most people are more comfortable with make, we'd like to keep the Makefile working for now. We are fine with having both tox and make until we get used to it.