Re: [julia-users] Module documentation not formatting properly
Works for me on 0.4.1. What release are you on? --Tim On Tuesday, November 17, 2015 06:50:37 AM NotSoRecentConvert wrote: > Is there a special way of documenting a module and its functions? > > When I document the module itself I am able to get full markdown formatting > but when I move on to the functions it will do the title but the rest > defaults to code formatting despite all of my efforts. > > "# Test > > `This` will work." > module Test >"# This Title Works > >`The rest` here is shown literally." >function x > >end > end
Re: [julia-users] Module documentation not formatting properly
Hmm, the little example works but my code still doesn't. I've trimmed my code down to something smaller that still misbehaves. "# Eddy Meas Module The Eddy Meas module is a collection of functions to work with SLT files generated by EddySoft and, more specifically, EddyMeas. `sltload`: Load SLT files based on dates `sltheader`: Load SLT header info `sltread`: Read SLT file converting everything except mV signals `sltconfig`: Load CFG data `slttimeshift`: Shift a set of SLT files' time `sltwrite`: Write data to an SLT file `slttrim`: Remove columns from SLT files For more information see each function's help. --- \n Requirements\n * DataFrames * dirlist.jl * findnewton.jl" module Test export slttrim function slttrim() println("\n###") println("## slttrim ##") println("###") println("slttrim(source,destination,mindate,maxdate,maxanalogcols)") println("\tsource::ASCIIString = Source directory, \"K:\\Data\"") println("\tdestination::ASCIIString = Destination directory, \"K:\\Data\"") println("\tmindate::DateTime = Start of period to process") println("\tmaxdate::DateTime = End of period to process") println("\tmaxanalogcols::Int64 = Maximum number of columns that should remain") end # slttrim() "# slttrim Remove columns from SLT files, source files must not have all equal numbers of columns `slttrim(source::ASCIIString,destination::ASCIIString,mindate::DateTime,maxdate::DateTime,maxanalogcols::Int64)`\n * source::ASCIIString = Source directory, `\"K:\\Data\" * destination::ASCIIString = Destination directory, `\"K:\\Data\" * mindate::DateTime = Start of period to process * maxdate::DateTime = End of period to process * maxanalogcols::Int64 = Maximum number of columns that should remain" function slttrim(f1::ASCIIString,f2::ASCIIString,mindate::DateTime, maxdate::DateTime,maxanalogcols::Int64) end end Julia Version 0.4.1 Commit cbe1bee (2015-11-08 10:33 UTC) Platform Info: System: Linux (x86_64-linux-gnu) CPU: Intel(R) Core(TM) i5-4570 CPU @ 3.20GHz WORD_SIZE: 64 BLAS: libopenblas (NO_LAPACK NO_LAPACKE DYNAMIC_ARCH NO_AFFINITY Haswell) LAPACK: liblapack.so.3 LIBM: libopenlibm LLVM: libLLVM-3.3
Re: [julia-users] Module documentation not formatting properly
Single-quoted strings don't strip leading whitespace, which means that in the second docstring is being treated as an indented code block. For any docstring longer than a single line triple-quoted strings should be used instead. - Mike On Wednesday, 18 November 2015 11:38:25 UTC+2, NotSoRecentConvert wrote: > > Hmm, the little example works but my code still doesn't. I've trimmed my > code down to something smaller that still misbehaves. > > "# Eddy Meas Module > > The Eddy Meas module is a collection of functions to work with SLT files > generated by EddySoft and, more specifically, EddyMeas. > > `sltload`: Load SLT files based on dates > > `sltheader`: Load SLT header info > > `sltread`: Read SLT file converting everything except mV signals > > `sltconfig`: Load CFG data > > `slttimeshift`: Shift a set of SLT files' time > > `sltwrite`: Write data to an SLT file > > `slttrim`: Remove columns from SLT files > > For more information see each function's help. > > --- > > \n > Requirements\n > * DataFrames > * dirlist.jl > * findnewton.jl" > module Test > > export slttrim > > function slttrim() > println("\n###") > println("## slttrim ##") > println("###") > println( > "slttrim(source,destination,mindate,maxdate,maxanalogcols)") > println("\tsource::ASCIIString = Source directory, \"K:\\Data\"") > println("\tdestination::ASCIIString = Destination directory, > \"K:\\Data\"") > println("\tmindate::DateTime = Start of period to process") > println("\tmaxdate::DateTime = End of period to process") > println("\tmaxanalogcols::Int64 = Maximum number of columns that > should remain") > end # slttrim() > > "# slttrim > > Remove columns from SLT files, source files must not have all equal > numbers of columns > > > `slttrim(source::ASCIIString,destination::ASCIIString,mindate::DateTime,maxdate::DateTime,maxanalogcols::Int64)`\n > * source::ASCIIString = Source directory, `\"K:\\Data\" > * destination::ASCIIString = Destination directory, `\"K:\\Data\" > * mindate::DateTime = Start of period to process > * maxdate::DateTime = End of period to process > * maxanalogcols::Int64 = Maximum number of columns that should remain" > function slttrim(f1::ASCIIString,f2::ASCIIString,mindate::DateTime, > maxdate::DateTime,maxanalogcols::Int64) > > end > end > > Julia Version 0.4.1 > Commit cbe1bee (2015-11-08 10:33 UTC) > Platform Info: > System: Linux (x86_64-linux-gnu) > CPU: Intel(R) Core(TM) i5-4570 CPU @ 3.20GHz > WORD_SIZE: 64 > BLAS: libopenblas (NO_LAPACK NO_LAPACKE DYNAMIC_ARCH NO_AFFINITY Haswell) > LAPACK: liblapack.so.3 > LIBM: libopenlibm > LLVM: libLLVM-3.3 >
Re: [julia-users] Module documentation not formatting properly
That was it. It works perfectly now. Thanks!
Re: [julia-users] Module documentation not formatting properly
When I fix it in the Test module it works but when I do the *exact same thing* in my module nothing is different.
Re: [julia-users] Module documentation not formatting properly
Not sure what the trouble is then. If possible could you post the entire module that's misbehaving as a gist, https://gist.github.com/? - Mike On Wednesday, 18 November 2015 12:25:48 UTC+2, NotSoRecentConvert wrote: > > When I fix it in the Test module it works but when I do the *exact same > thing* in my module nothing is different. >
Re: [julia-users] Module documentation not formatting properly
After further testing I think it has to do with caching. I copied more and more functions from the original module to the test one, testing each time. By the end I just copied and pasted everything, changing only the module name to Test in the test module. It worked with no problems. Then I tried the original module again and the same old errors came up. How do I reset the documentation cache of a module?
Re: [julia-users] Module documentation not formatting properly
It's a bit strange though. If I document functions which had no previously been documented in the original module and then try to load the documentation in REPL it *does* indeed show the new documentation but with incomplete formatting. When it's then copied and pasted into the Test module it then shows up correctly.
Re: [julia-users] Module documentation not formatting properly
Docs gets captured at macro expansion time so there's no simple way to reset the module's docstring cache other than just reloading the module completely. What are the steps you're going through when reloading the modules, which commands are you using? Are you restarting Julia between each try, or perhaps using `workspace()`? - Mike On Wednesday, 18 November 2015 16:02:07 UTC+2, NotSoRecentConvert wrote: > > After further testing I think it has to do with caching. I copied more and > more functions from the original module to the test one, testing each time. > By the end I just copied and pasted everything, changing only the module > name to Test in the test module. It worked with no problems. Then I tried > the original module again and the same old errors came up. > > How do I reset the documentation cache of a module? >
Re: [julia-users] Module documentation not formatting properly
I restart Julia. As far as I know it's the most thorough way of making sure it's reloaded properly. Then it's just the usual way of loading a module, *using Test*.
Re: [julia-users] Module documentation not formatting properly
Turns out it was a problem with the file. I still have no idea why but I just renamed the original as a backup and then renamed my test module to what I wanted. It worked! Before I did that I moved ~/.julia/v0.4 to check for caching issues. After it was done reloading everything it still didn't work so I moved on to the renaming test I mentioned above.
Re: [julia-users] Module documentation not formatting properly
Just a follow up from further discussion between NotSoRecentConvert and myself about this off-list: Turns out the differences in behaviour between the two files was that they had different line endings... namely `\r\n` and `\n`. Related: https://github.com/JuliaLang/julia/issues/11988. - Mike On Thursday, 19 November 2015 11:03:06 UTC+2, NotSoRecentConvert wrote: > > Turns out it was a problem with the file. I still have no idea why but I > just renamed the original as a backup and then renamed my test module to > what I wanted. It worked! > > Before I did that I moved ~/.julia/v0.4 to check for caching issues. After > it was done reloading everything it still didn't work so I moved on to the > renaming test I mentioned above. >