Doc licence - Githubissues

ghost commented 9 years ago

I removed all occurences of Unofficial and fake logo. You need to merge in master as it's a history rewrite.

n-riesco commented 9 years ago

I'm still considering our options. I'll come back to you... soon'ish. Sorry about the delay.

n-riesco commented 9 years ago

Hi Benjamin,

here's what I'm planning:

I'm planning to cherry-pick all your commits but those with the JS logo
I will replace your commits with the JS logo with commits that use a preliminary logo that I've developed
I will cherry-pick your commits from branch benjaminabel:user-documentation (since this is the branch I already reviewed)
When I'm done with the above, I will cherry-pick and review the missing commits from your branch benjaminabel:doc-license
At this point, I will merge into master

After merging into master, I have a small list of points (resulting from my previous review) that I'd like to address. I will come back to you on this.

ghost commented 9 years ago

Hi Nico,

The user documentation branch is just a cleaned branch in which i removed the unoffocial logo in evrry commit where it appeared and in which i removed yhe commit in which i added the fake logo, you don't need to rereview all commits I didn't change anything else.

So if you don't care that the links are broken in the graphics tutorial in some commits in the history then you should merge that branch and then add the logo with the correct link to fix the link.

n-riesco commented 9 years ago

I haven't merged to master. Unfortunately, the documentation fails to build on my machine. I've created a new branch name doc with the commits I intent to merge once the build problem is fixed.

This is the error I get on Ubuntu 14.04 LTS:

> ijavascript@5.0.0 doc:nb /home/nriesco/Documents/sync/src/github.com/ijavascript
> ipython nbconvert --template 'doc/templates/ipython' 'doc/tutorials/ipynb/*.ipynb' --FilesWriter.build_directory='doc/output'

[NbConvertApp] Using existing profile dir: u'/home/nriesco/.config/ipython/profile_default'
[NbConvertApp] Converting notebook doc/tutorials/ipynb/hello.ipynb to html
[NbConvertApp] Support files will be in hello_files/
[NbConvertApp] Loaded template doc/templates/ipython.tpl
Traceback (most recent call last):
  File "/usr/bin/ipython", line 6, in <module>
    start_ipython()
  File "/usr/lib/python2.7/dist-packages/IPython/__init__.py", line 118, in start_ipython
    return launch_new_instance(argv=argv, **kwargs)
  File "/usr/lib/python2.7/dist-packages/IPython/config/application.py", line 546, in launch_instance
    app.start()
  File "/usr/lib/python2.7/dist-packages/IPython/terminal/ipapp.py", line 358, in start
    return self.subapp.start()
  File "/usr/lib/python2.7/dist-packages/IPython/nbconvert/nbconvertapp.py", line 267, in start
    self.convert_notebooks()
  File "/usr/lib/python2.7/dist-packages/IPython/nbconvert/nbconvertapp.py", line 300, in convert_notebooks
    output, resources = exporter.from_filename(notebook_filename, resources=resources)
  File "/usr/lib/python2.7/dist-packages/IPython/nbconvert/exporters/exporter.py", line 289, in from_filename
    return self.from_notebook_node(nbformat.read(f, 'json'), resources=resources,**kw)
  File "/usr/lib/python2.7/dist-packages/IPython/nbconvert/exporters/exporter.py", line 260, in from_notebook_node
    output = self.template.render(nb=nb_copy, resources=resources)
  File "/usr/lib/python2.7/dist-packages/jinja2/environment.py", line 969, in render
    return self.environment.handle_exception(exc_info, True)
  File "/usr/lib/python2.7/dist-packages/jinja2/environment.py", line 742, in handle_exception
    reraise(exc_type, exc_value, tb)
  File "./doc/templates/ipython.tpl", line 4, in top-level template code
    {%- extends 'basic.tpl' -%}
TemplateNotFound: basic.tpl

If you suspect this is an IPython bug, please report it at:
    https://github.com/ipython/ipython/issues
or send an email to the mailing list at ipython-dev@scipy.org

You can print a more detailed traceback right now with "%tb", or use "%debug"
to interactively debug it.

Extra-detailed tracebacks for bug-reporting purposes can be enabled via:
    c.Application.verbose_crash=True

n-riesco commented 9 years ago

The error is due to IPython v1.2.1 using html_basic.tpl instead of basic.html. But even after this change, the build fails because mathjax.tpl is missing.

n-riesco commented 9 years ago

Pasting the mathjax macro into doc/templates/ipython.tpl worked around the problem. Next issue is that doc/templates/empty_md.ipynb is in v4 format.

n-riesco commented 9 years ago

Converting doc/templates/empty_md.ipynb to v3 format seems to fix the problem.

The documentation is generated but it seems to have a broken link to the CSS file (npm run doc:style creates a CSS file in doc/templates/jsdoc_templates/static/styles/ipython_style.css, whereas doc/output/index.html expects it in doc/output/jsdoc/styles).

I've copied the CSS file by hand to doc/output/jsdoc/styles and now the navigation bar looks better, but yet not as neat as in http://benjaminabel.github.io/ijavascript/

Now I need to work on something else. I'll come back to this at a later time.

ghost commented 9 years ago

Hi Nico, I think you should use a more recent version of ipython, if you're using Ubuntu 14.04 and you want to use ipython3.1 with python 3 (that's what I use on a virtualenv) try:

sudo apt-get install python3-pip
sudo pip3 install --upgrade ipython jsonschema jinja2 pygments mistune

and then npm run doc should work. I also recommend you to use virtualenv or mkvirtualenvwrapper if you don't want to mix all your python environments.

If you want I can update the contributing file to explain this process.

n-riesco commented 9 years ago

Let me work on this branch and see what I can come up with.

ghost commented 9 years ago

If you change the templates it will not work on recent ipython versions, 1.2.1 is really old, and latest commit was on Feb 24, 2014 .

n-riesco commented 9 years ago

Hi Benjamin,

I'm already done merging and cleaning up the commits from the doc branch.

I ended up creating a python script scripts/doc-build.py to build the website. This script is in python, because, to ensure the compatibility with IPython v1.2.1, it requires some functionality from nbconvert that isn't available through the command line. See commit b4b067695a90abd341307d11b5e4a68fabb72ea4 for details.

I've also added doc/index.json to index all the tutorials linked in the website. This index currently allows ordering the tutorials by author, but in the future, I plan to order the tutorials also by topic.

I intend to use this index of tutorials to encourage contributions in the form of Javascript tutorials.

n-riesco / ijavascript

Doc licence #26