Migrate doc from Sphinx to Documenter #347

s-celles · 2017-11-13T09:45:53Z

Convert rst to md using https://gist.github.com/zaiste/77a946bbba73f5c4d33f3106a494e6cd
Add Julia syntax highlighting to md files
Add make.jl for Documenter.jl
Autodeploy doc in .travis.yml
Closes #346

Convert rst to md using https://gist.github.com/zaiste/77a946bbba73f5c4d33f3106a494e6cd Add Julia syntax highlighting to md files Add make.jl for Documenter.jl Autodeploy doc in .travis.yml Closes JuliaCollections#346

s-celles · 2017-11-13T09:47:36Z

Pandoc have been used to convert reStructuredText to Markdown using:

FILES=*.rst
for f in $FILES
do
  filename="${f%.*}"
  echo "Converting $f to $filename.md"
  pandoc $f -f rst -t markdown -o $filename.md
done

s-celles · 2017-11-13T09:51:13Z

https://github.com/JuliaCollections/DataStructures.jl/pull/347/files#diff-333026e9bbc6f22aa98e849abacab9d7

doc/src/sorted_containers.md

need some manual improvements

codecov · 2017-11-13T09:58:02Z

Codecov Report

Merging #347 into master will increase coverage by 0.04%.
The diff coverage is 100%.

@@            Coverage Diff            @@
##           master    #347      +/-   ##
=========================================
+ Coverage   96.45%   96.5%   +0.04%     
=========================================
  Files          31      31              
  Lines        2286    2287       +1     
=========================================
+ Hits         2205    2207       +2     
+ Misses         81      80       -1

Impacted Files	Coverage Δ
src/sorted_set.jl	`93.71% <ø> (ø)`	⬆️
src/sorted_dict.jl	`98.31% <100%> (ø)`	⬆️
src/sorted_multi_dict.jl	`92.92% <100%> (ø)`	⬆️
src/default_dict.jl	`97.22% <0%> (ø)`	⬆️
src/priorityqueue.jl	`99.13% <0%> (ø)`	⬆️
src/ordered_dict.jl	`86.91% <0%> (+0.11%)`	⬆️
src/DataStructures.jl	`100% <0%> (+11.11%)`	⬆️

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 71e6001...3062f22. Read the comment docs.

s-celles · 2017-11-13T10:07:42Z

Definition list in doc/src/sorted_containers.md is not rendered correctly.

Any idea how to fix this?

because this is Documenter.jl's default

kmsquire · 2017-11-13T17:28:25Z

@scls19fr, thanks for doing this! I've been going through my messages in order, and finally caught up to this one (so most of my previous comments were out of date).

Not sure I'll have more time today, but will try to take a closer look over the next couple of days.

StephenVavasis · 2017-11-13T20:43:03Z

Approximately 2-3 years ago when I wrote the code for sorted containers, I switched all the DataStructures documentation from MD to RST by hand (with Kevin's permission) precisely because I couldn't figure out how to make definition lists in MD, and I needed definition lists for the sorted containers documentation.

s-celles · 2017-11-13T21:04:23Z

Fashion is an eternal renewal ;-)
I personally prefer (running) doctests than pretty definition lists.
Maybe a workaround could be to use header h... instead of definition lists.
See also https://www.google.fr/search?q=definition+list+markdown

kmsquire · 2017-11-18T19:58:27Z

Okay, had a look. :-)

Regarding doc/src/sorted_containers.md formatting: since the definition lists there are used to document the types and functions/methods defined for sorted containers, the best solution would be to move these definitions into the source code as docstrings, and then follow the Documenter.jl instructions for including those docstrings in the documentation.

Would you be up to doing that here? It should probably be done for all methods/types, but since sorted containers are the most problematic, I think just doing it there for now would be fine. The rest can be moved gradually--e.g., as the package is being split up (cc: @oxinabox).

StephenVavasis · 2017-11-18T20:14:49Z

Just a remark that some of the functions in the sorted container function list apply to more than one of the sorted containers and hence correspond to more than one location in the source code.

s-celles · 2017-11-19T11:48:18Z

I moved most definitions in doc/src/sorted_containers.md to their respective function definitions (duplicating into several files when required).

kmsquire

Thanks, this looks good! I made a few minor requests for changes.

kmsquire · 2017-11-19T15:21:14Z

src/sorted_dict.jl

+    SortedDict(o, k1=>v1, k2=>v2, ...)
+
+Construct a `SortedDict` from the given pairs with the specified
+ordering `o`. If `K` and `V` are not specified, the key type and


K and V don't appear here.

kmsquire · 2017-11-19T15:23:23Z

src/sorted_dict.jl

+`key=>value` pairs. If `K` and `V` are not specified, the key type
+and value type are inferred from the given iterable. The ordering
+object `o` defaults to `Forward`.
+"""
 SortedDict{K,D}(kv) where {K,D} = SortedDict{K,D}(Forward, kv)
 function SortedDict{K,D}(o::Ord, kv) where {K,D,Ord<:Ordering}


The function signature here doesn't match the one in the comments above. Might need to rearrange the definitions a little.

The problem is is similar to #340 and should probably be adressed in an other PR

kmsquire · 2017-11-19T15:23:45Z

src/sorted_dict.jl

+to `Forward`.
+
+See below for more information about ordering.
+"""
 SortedDict(kv, o::Ordering=Forward) = SortedDict(o, kv)
 function SortedDict(o::Ordering, kv)


kmsquire · 2017-11-19T15:25:56Z

src/sorted_set.jl

@@ -5,6 +5,19 @@
 mutable struct SortedSet{K, Ord <: Ordering}
    bt::BalancedTree23{K,Void,Ord}

+    """
+        SortedSet(iter, o=Forward)
+    and


I personally think that the "and" lines are not needed (here and elsewhere).

s-celles · 2017-11-19T16:42:04Z

I've just add references to docstrings into sorted_containers.md

about "and" lines... that's difficult to avoid them (at least in this PR)

Some constructors's docstring will probably have to be modified... but I think it's safer to adress this problem in an other PR.

kmsquire · 2017-11-19T22:12:18Z

This looks good--as you suggested, I'm okay with fixing the remaining issues in future pull requests.

However, there are merge conflicts now. Are you comfortable fixing these? I can give some command-line help if you need it.

s-celles · 2017-11-20T10:47:23Z

My git fu is a bit rusty... So some help to deal with this 2 conflicting files could help.
I can squash commit if you prefer. I can only do it tonight or tomorrow.

s-celles · 2017-11-20T20:42:30Z

Solving this merge conflict wasn't easy for me (and I don't like this kind of task)... but I think it's now ready for merging.
As told in this comment #347 (comment) some improvement could be done after this PR being merged.

s-celles · 2017-11-29T16:57:59Z

Current doc is available at ReadTheDocs http://datastructuresjl.readthedocs.io/en/latest

I wonder if it was manually uploaded or automatically uploaded when commits are made.

Documenter.jl provides a nice doc about hosting on github pages https://juliadocs.github.io/Documenter.jl/stable/man/hosting/

I wonder if we should move out of RTD to GH-pages or not...

and who can do it?

If some improvements to this PR are required please tell me.

ViralBShah · 2017-12-03T14:05:46Z

Should we merge this before #348?

kmsquire · 2017-12-04T06:54:44Z

Sorry, been swamped recently, but I plan to look at this tomorrow.

s-celles · 2017-12-18T09:55:01Z

Any news about this PR? Is there any problems on which I could help? I noticed that some recent PR involve a lot of changes in several files. I would prefer to avoid to have to rebase this PR.

kmsquire · 2017-12-19T02:06:37Z

Again, swamped (and sick right now). Is anyone else available to

Review
Make the switch to github pages that (I think) this requires?

oxinabox · 2017-12-20T06:00:32Z

I will try and hit this up in the next few days.

What I want to do is branch this branch over to my own repo,
setup github pages on that.
And actually review what it looks like and that the github pages deployment stuff is working right.
(I've only set that up once before I think i mostly followed https://www.juliabloggers.com/finalizing-your-julia-package-documentation-testing-coverage-and-publishing/
but maybe there is better instruction in the Documentor.jl docs now.)

oxinabox · 2018-01-04T07:39:29Z

Sorry, there were reasons, but anyway I am doing my review right now.
If I can finish it in 1hr then this will be done

oxinabox · 2018-01-04T09:09:17Z

It seems to be working but I get a couple of errors, that I can't quiet workout why (I think you mentioned them before)

Documenter: setting up build directory.
Documenter: expanding markdown templates.
Documenter: building cross-references.
 !! No doc found for reference '[`Bool`](@ref)'. [src/sorted_containers.md]
Documenter: running document checks.
 > checking for missing docstrings.
 > running doctests.
 > checking footnote links.
Documenter: populating indices.
Documenter: rendering document.
 !! Invalid local link: unresolved path
    '@ref' in sorted_containers.md
 ?? TRAVIS_REPO_SLUG       = ""
 ??   should match "github.com/oxinabox/DataStructures.jl.git" (kwarg: repo)
 ?? TRAVIS_PULL_REQUEST    = ""
 ??   deploying if equal to "false"
 ?? TRAVIS_OS_NAME         = ""
 ??   deploying if equal to "linux" (kwarg: osname)
 ?? TRAVIS_JULIA_VERSION   = ""
 ??   deploying if equal to "0.6" (kwarg: julia)
 ?? TRAVIS_BRANCH          = ""
 ?? TRAVIS_TAG             = ""
 ??   deploying if branch equal to "master" (kwarg: latest) or tag is set
 ?? git commit SHA         = f38d438
 ?? DOCUMENTER_KEY exists  = false
 ?? should_deploy          = false
Documenter: skipping docs deployment.
  You can set DOCUMENTER_DEBUG to "true" in Travis to see more information.

I'm not sure if this is a blocking or not.
I can't see what is causing it, as those lines don't seem to exist in /docs/src/sorted_container.md

I am going to push a few changes over to this branch shortly from my staging branch.

You can see my staging site at:
http://white.ucc.asn.au/DataStructures.jl/latest/priority-queue.html

Others can check if that is good, it will stay hosted for a while.
Probably long after this is merged.

(Was blank on sphinx anyway)

oxinabox · 2018-01-04T10:15:07Z

After being merged, this needs the deploy key added to travis and github.
Which I can do, and will do when I merge in ~24 hours.

People should take a look at the staging site:
http://white.ucc.asn.au/DataStructures.jl/latest

s-celles · 2018-01-04T10:38:52Z

http://white.ucc.asn.au/DataStructures.jl/latest/disjoint_sets.html

maybe comments (starting with #...) should be aligned

Same for http://white.ucc.asn.au/DataStructures.jl/latest/accumulators.html (see push!)

On http://white.ucc.asn.au/DataStructures.jl/latest/default_dict.html
‘Notethatinthelastexample,weneedtouseafunctiontocreateeachnew‘Notethatinthelastexample,weneedtouseafunctiontocreateeachnew
looks odd.

s-celles · 2018-01-04T10:48:56Z

http://white.ucc.asn.au/DataStructures.jl/latest/trie.html

Being previously a big fan of Python and PEP8 I will change

t=Trie{Int}()

to

t = Trie{Int}()

same for others affectations

t["Rob"]=42

->

t["Rob"] = 42

same for

t["Roger"]=24

->

t["Roger"] = 24

I will add a space after coma, and two spaces before # and 1 space after #

haskey(t,"Rob") #true

->

haskey(t, "Rob")  # true

Same for

get(t,"Rob",nothing) #42

->

get(t, "Rob", nothing)  # 42

but these cosmetic changes could be tackled later if you prefer.

oxinabox · 2018-01-04T11:37:07Z

Do it now, or do it later, I don't mind.

oxinabox · 2018-01-04T12:55:30Z

I have now looked over the output and am satisfied nothing has gone critically wrong.

s-celles · 2018-01-04T13:11:31Z

Ok so let's publish it now under https://juliacollections.github.io/DataStructures.jl/latest and fix remaining issues later.

oxinabox · 2018-01-04T14:19:43Z

I've added the hooks so that when I (or someone else) merges this tomorrowish, then the docs should just build and deploy.

oxinabox · 2018-01-05T00:21:54Z

Ok, Done 🎉
Thank you for your work, it was fairly mammoth.
Sorry about how long it took for the code review to happen.

oxinabox · 2018-01-05T00:43:19Z

Yes, I just clicked merge, and 5 minutes later (once travis run) new docs appeared at the new site.
Now I need to workout how to take down the old ones.

s-celles · 2018-01-05T03:43:10Z

Thanks @oxinabox for merging

Migrate doc from Sphinx to Documenter

c31f17f

Convert rst to md using https://gist.github.com/zaiste/77a946bbba73f5c4d33f3106a494e6cd Add Julia syntax highlighting to md files Add make.jl for Documenter.jl Autodeploy doc in .travis.yml Closes JuliaCollections#346

Fix headers

6fc555b

s-celles added 2 commits November 13, 2017 11:10

docs -> doc

fd64fbb

doc -> docs

fc69eb6

because this is Documenter.jl's default

Change h1 title syntax

1edb191

s-celles added 2 commits November 19, 2017 12:42

WIP

ad4dd1d

Fix bold

5eb5a9a

s-celles added 3 commits November 19, 2017 14:50

Fix gt

7e90f25

Reorder pages

d1f84f0

Add content

0db32ec

kmsquire requested changes Nov 19, 2017

View reviewed changes

Add references to docstrings into sorted_containers

d010aa5

Minor docstring fixes

9865bb4

kmsquire approved these changes Nov 19, 2017

View reviewed changes

Merge branch 'master' into fix346_documenter

ceb450a

oxinabox mentioned this pull request Dec 6, 2017

Split up the package? #310

Open

oxinabox mentioned this pull request Jan 4, 2018

Stage fix346 documenter #354

Closed

oxinabox added 3 commits January 4, 2018 17:50

=documenter.jl to autodeploy on test site

f006207

Delete broken Sphinx index stuff

f6ecf8c

(Was blank on sphinx anyway)

Don't point at staging site

63d5b3f

Update link in readme

3062f22

oxinabox merged commit 12c267b into JuliaCollections:master Jan 5, 2018

oxinabox mentioned this pull request Jan 5, 2018

Redirect (or at least make as outdated) the ReadTheDocs site #355

Closed

s-celles mentioned this pull request Jan 5, 2018

Minor cosmetic fixes for doc are required #356

Closed

Migrate doc from Sphinx to Documenter #347

Migrate doc from Sphinx to Documenter #347

Conversation

s-celles commented Nov 13, 2017

s-celles commented Nov 13, 2017 • edited Loading

s-celles commented Nov 13, 2017 • edited Loading

codecov bot commented Nov 13, 2017 • edited Loading

Codecov Report

s-celles commented Nov 13, 2017 • edited Loading

kmsquire commented Nov 13, 2017

StephenVavasis commented Nov 13, 2017 • edited Loading

s-celles commented Nov 13, 2017

kmsquire commented Nov 18, 2017

StephenVavasis commented Nov 18, 2017

s-celles commented Nov 19, 2017

kmsquire left a comment

Choose a reason for hiding this comment

kmsquire Nov 19, 2017

Choose a reason for hiding this comment

kmsquire Nov 19, 2017

Choose a reason for hiding this comment

s-celles Nov 19, 2017

Choose a reason for hiding this comment

kmsquire Nov 19, 2017

Choose a reason for hiding this comment

kmsquire Nov 19, 2017

Choose a reason for hiding this comment

s-celles commented Nov 19, 2017

kmsquire commented Nov 19, 2017

s-celles commented Nov 20, 2017

s-celles commented Nov 20, 2017

s-celles commented Nov 29, 2017 • edited Loading

ViralBShah commented Dec 3, 2017

kmsquire commented Dec 4, 2017

s-celles commented Dec 18, 2017

kmsquire commented Dec 19, 2017

oxinabox commented Dec 20, 2017

oxinabox commented Jan 4, 2018

oxinabox commented Jan 4, 2018 • edited Loading

oxinabox commented Jan 4, 2018

s-celles commented Jan 4, 2018

s-celles commented Jan 4, 2018 • edited Loading

oxinabox commented Jan 4, 2018

oxinabox commented Jan 4, 2018

s-celles commented Jan 4, 2018 • edited Loading

oxinabox commented Jan 4, 2018

oxinabox commented Jan 5, 2018

oxinabox commented Jan 5, 2018

s-celles commented Jan 5, 2018

s-celles commented Nov 13, 2017 •

edited

Loading

s-celles commented Nov 13, 2017 •

edited

Loading

codecov bot commented Nov 13, 2017 •

edited

Loading

s-celles commented Nov 13, 2017 •

edited

Loading

StephenVavasis commented Nov 13, 2017 •

edited

Loading

s-celles commented Nov 29, 2017 •

edited

Loading

oxinabox commented Jan 4, 2018 •

edited

Loading

s-celles commented Jan 4, 2018 •

edited

Loading

s-celles commented Jan 4, 2018 •

edited

Loading