search

sandialabs / Gulliver

Gulliver is a C# utility package and library engineered for the manipulation of arbitrary sized byte arrays accounting for appropriate endianness and jagged byte length.
Apache License 2.0
15 stars 3 forks source link

Documentation structure update #25

Closed rheone closed 5 years ago

rheone commented 5 years ago

Addresses #21 fixes Sphinx document template width Addresses #22 Converting Sphinx markdown documentation to restructured text

Attached is compiled docs html.zip

ahsteele commented 5 years ago

I haven’t looked at the diffs yet, but does this conform to a standard for HTML heading markup?

rheone commented 5 years ago

RestructuredText you mean? The headings are “correct” but likely not consistent per document. Such can be amended before completion.

rheone commented 5 years ago

@ahsteele The RestructuredText headings are now normalized as per Sphinx and RST syntax guide (0.9.3)

  • # with overline, for parts
  • * with overline, for chapters
  • =, for sections
  • -, for subsections
  • ^, for subsubsections
  • “, for paragraphs

Adds build docs

Added a new Building page to docs so as other developers can also build the project and doc and their machines. hint hint This covers the the optional use of psake, building docs and building c# code and generating packages via command line.

See attached zip for rendered docs

html.zip

ahsteele commented 5 years ago

Should we put this somewhere in the documentation or other guidelines so that we can refer back to it? I know I’ll have to look it up and shipping it with the project will be easier than Google for the syntax guide each time.

The RestructuredText headings are now normalized as per Sphinx and RST syntax guide (0.9.3)

  • # with overline, for parts
  • * with overline, for chapters
  • =, for sections
  • -, for subsections
  • ^, for subsubsections
  • “, for paragraphs
rheone commented 5 years ago

Should we put this somewhere in the documentation or other guidelines so that we can refer back to it? I know I’ll have to look it up and shipping it with the project will be easier than Google for the syntax guide each time.

The RestructuredText headings are now normalized as per Sphinx and RST syntax guide (0.9.3)

  • # with overline, for parts
  • * with overline, for chapters
  • =, for sections
  • -, for subsections
  • ^, for subsubsections
  • “, for paragraphs

I'm ready to write a style guideline, nor am I sure I ever will be. I think that's where the heading stuff would belong. I'll open an issue for a style guide and include the heading ordering. We can use that as a stop gap for the moment until something more "official" is created.

See #27 [Doc] Create a style guideline