Publish.jl: A Universal Document Authoring Package for Julia

Publish.jl

A universal document authoring package for Julia.  

Disclaimer

Currently this package should be regarded as experimental --- a proving ground for new features for the Julia documentation ecosystem rather than a mature and proven piece of software. If you need a solution that will definitely work, look at Documenter.jl instead.

This is a package for Julia that provides a general framework for writing prose --- technical documentation is its focus, though it is general enough to be applied to any kind of written document.

Some standout features:

  • built-in live server to view your changes in real-time,
  • uses a fully-compliant commonmark parser, CommonMark.jl,
  • produces HTML and PDF files natively, no LaTeX dependencies to manage yourself,
  • publication-quality PDF generation uses tectonic for self-contained, reproducible builds,
  • combine markdown files, Jupyter notebooks, and Julia files for your content,
  • supports themes to customise both HTML and PDF output,
  • and declarative configuration built on top of Julia's Pkg.jl package manager.

Publish can scale from single pages all the way to large cross-referenced multi-project documents.

To jump straight in and begin using Publish run the following in your Julia REPL:

pkg> add Publish

julia> using Publish

julia> serve(Publish)
✓ LiveServer listening on http://localhost:8000/ ...
  (use CTRL+C to shut down)

The above will install Publish, import it, and then start up a local web-server for Publish's own documentation --- the content you're reading right now. Open the link in your web browser and then continue on to the next section, Getting Started.

Download Details:

Author: MichaelHatherly
Source Code: https://github.com/MichaelHatherly/Publish.jl 
License: View license

#julia #markdown #publish 

What is GEEK

Buddha Community

Publish.jl: A Universal Document Authoring Package for Julia

Publish.jl: A Universal Document Authoring Package for Julia

Publish.jl

A universal document authoring package for Julia.  

Disclaimer

Currently this package should be regarded as experimental --- a proving ground for new features for the Julia documentation ecosystem rather than a mature and proven piece of software. If you need a solution that will definitely work, look at Documenter.jl instead.

This is a package for Julia that provides a general framework for writing prose --- technical documentation is its focus, though it is general enough to be applied to any kind of written document.

Some standout features:

  • built-in live server to view your changes in real-time,
  • uses a fully-compliant commonmark parser, CommonMark.jl,
  • produces HTML and PDF files natively, no LaTeX dependencies to manage yourself,
  • publication-quality PDF generation uses tectonic for self-contained, reproducible builds,
  • combine markdown files, Jupyter notebooks, and Julia files for your content,
  • supports themes to customise both HTML and PDF output,
  • and declarative configuration built on top of Julia's Pkg.jl package manager.

Publish can scale from single pages all the way to large cross-referenced multi-project documents.

To jump straight in and begin using Publish run the following in your Julia REPL:

pkg> add Publish

julia> using Publish

julia> serve(Publish)
✓ LiveServer listening on http://localhost:8000/ ...
  (use CTRL+C to shut down)

The above will install Publish, import it, and then start up a local web-server for Publish's own documentation --- the content you're reading right now. Open the link in your web browser and then continue on to the next section, Getting Started.

Download Details:

Author: MichaelHatherly
Source Code: https://github.com/MichaelHatherly/Publish.jl 
License: View license

#julia #markdown #publish 

Documenter.jl: A Documentation Generator for Julia

Documenter

A documentation generator for Julia.

Installation

The package can be installed with the Julia package manager. From the Julia REPL, type ] to enter the Pkg REPL mode and run:

pkg> add Documenter

Or, equivalently, via the Pkg API:

julia> import Pkg; Pkg.add("Documenter")

Documentation

  • STABLEdocumentation of the most recently tagged version.
  • DEVELdocumentation of the in-development version.

Project Status

The package is tested against, and being developed for, Julia 1.6 and above on Linux, macOS, and Windows.

Questions and Contributions

Usage questions can be posted on the Julia Discourse forum under the documenter tag, in the #documentation channel of the Julia Slack and/or in the JuliaDocs Gitter chat room.

Contributions are very welcome, as are feature requests and suggestions. Please open an issue if you encounter any problems. The contributing page has a few guidelines that should be followed when opening pull requests and contributing code.

Related packages

There are several packages that extend Documenter in different ways. The JuliaDocs organization maintains:

Other third-party packages that can be combined with Documenter include:

Finally, there are also a few other packages in the Julia ecosystem that are similar to Documenter, but fill a slightly different niche:

Download Details:

Author: JuliaDocs 
Source Code: https://github.com/JuliaDocs/Documenter.jl 
License: MIT license

#julia #docs #document 

Publish.jl: Julia Package for Publishing Code

Publish

This package uses Latex to generate a PDF containing some file's code and output. The result looks similar to that produced by MATLAB's publish function. This is particularly useful if you have to submit code with problem sets.

Installation

To install, enter Julia and run the following:

Pkg.clone("https://github.com/dressel/Publish.jl.git")

Basic Usage

using Publish
publish("code.jl")

Currently, this will generate a PDF called "code.pdf" that contains the code, any printed output, and any plots generated by the code. The output and plots are generated by running the code itself. Plotting is currently handled with PGFPlots.jl.

If you just want to print the code without running it, specify the optional runcode parameter:

publish("code.jl", runcode=false)

Plotting

Plotting is currently handled with the Julia PGFPlots package. Any time you use the save function with PGFPlots, that plot is saved to the PDF.

Required Tex Packages

  • listings to plot the code
  • caption forgot why we need this
  • standalone for plots
  • xcolor for pgfplots, listings stuff
  • pgfplots for plotting
  • geometry to change margins

Example File

An example file named sample_file.jl and its corresponding pdf can be found in the examples folder. To try generating this on your own, run the code below. It will copy the sample file to your current directory (with the name publish_package_sample.jl to avoid any potential conflicts). You should then be able to publish the code.

require(Publish/examples/copy_sample.jl")
using Publish
publish("publish_package_sample.jl")

Notes

If you publish a file in another folder, as in:

publish("folder/file.jl")

This will put the pdf and tex file in the directory named folder.

Any time you publish a file, a .pdf and a .tex file will be saved.

Any time your code saves a plot (using PGFPlots), a .tex file will be saved for it.

TODO list

  • Make some test julia files and stick them in the test folder
  • Allow publishing of other languages (obviously, can't run that code)
  • Include another publishing format that doesn't rely on Latex (md, html)
  • improve listings language file (in julia_listings.tex)
  • Robust to not having things like pgfplots. Just don't plot in that case
  • Override display, so printing arrays can look pretty
  • Make the Output style look better
  • If a file includes another file, should that file be displayed too?

Download Details:

Author: Dressel
Source Code: https://github.com/dressel/Publish.jl 
License: View license

#julia #publishing #code 

Help.jl: Query Documentation From Julia Prompt

Help.jl

Search through readme and documentation of packages and functions based on a query. Unlike apropos, Help uses TF-IDF instead of sub-string search.

Run update() first to build the data needed for search.

Example

julia> using Help
julia> help("Gray scale an image")
Help Results
---------
1. Images
2. ImageView
3. TestImages
4. ImageRegistration
5. SloanDigitalSkySurvey

julia> using MySQL
julia> help(MySQL, "get the last inserted id")
Help Results
---------
1. mysql_insert_id

julia> help(Base, "convert pointer to array")
Help Results
---------
1. pointer_to_array
2. oftype
3. bitpack

Download Details:

Author: nkottary 
Source Code: https://github.com/nkottary/Help.jl 
License: View license

#julia #query #documentation 

Roxygen.jl: A Roxygen-like Documentation Package

Roxygen.jl

A draft implementation of a Roxygen-like package for automatically generating documentation from Julia source files.

Basic Format

The following file shows how a Julia file can use Roxygen through specially formatted comments:

#' @@name count
#'
#' @@description
#'
#' Count the number of missing values in every column of an
#' AbstractDataFrame.
#'
#' @@arg adf::AbstractDataFrame An AbstractDataFrame.
#' @@arg skip::Int The index of a column to skip.
#'
#' @@return missing::Vector{Int} The number of missing values in each column.
#' @@return success::Bool Did the operation complete successfully?
#'
#' @@examples
#'
#' df = DataFrame(A = 1:3, B = ["x", "y", "z"])
#' count(df)

function count(adf::AbstractDataFrame, skip::Int)
    return Int[], false
end

#' @@name sum
#'
#' @@description
#'
#' Sum the elements of each column of an AbstractDataFrame.
#'
#' @@arg adf::AbstractDataFrame An AbstractDataFrame.
#'
#' @@return sums::Vector{Float64} The sums of each column's entries.
#'
#' @@examples
#'
#' df = DataFrame(A = 1:3, B = ["x", "y", "z"])
#' sum(df)

function sum(adf::AbstractDataFrame)
    return Float64[]
end

This file contains Julia code as well as comments that use a set of directives, like @@arg and `@@return`` to describe properties of the function being documented. The valid directives and requirements for their use are described below:

  • @@name: The name of the function. A name directive usage must look like @@name NAME with whitespace after the directive and a single name after the initial whitespace.
  • @@exported: Is the function exported by the package being documented?
  • @@description: A short summary of the use and purpose of the function.
  • @@arg: A summary of each argument of a function in the order required by the function. Must contain argument name, argument type and a short verbal description.
  • @@field: A summary of each field of a composite type in the order required by the type's constructor. Must contain field name, field type and a short verbal description.
  • @@return: A summary of each return value of a function in the order returned by the function. Must contain value name, value type and a short verbal description.
  • @@examples: A free-form set of examples of the function or type's use.

Usage Example

To generate documentation for all .jl files in the src directory and place this documentation in the doc directory, run the following command:

using Roxygen
roxygenize("src", "doc")

Only files from the source directory that contained Roxygen documentation will give rise to files in the output directory.

Download Details:

Author: johnmyleswhite
Source Code: https://github.com/johnmyleswhite/Roxygen.jl 
License: View license

#julia #documentation