Doctor
A tool to generate documentation quickly
NPM Package: https://www.npmjs.com/package/doctormake
GitHub Repo: https://github.com/Merkoba/Doctor
NPM Package: https://www.npmjs.com/package/doctormake
GitHub Repo: https://github.com/Merkoba/Doctor
Doctor allows you to build documentation for your project through XML syntax.
It can be configured through some settings, and different sections of the documentation can be created, which are fully HTML compatible.
To generate the single HTML file output, the source file is passed to doctormake (NPM package):
Or manually:
This is meant to be a simple one-page documentation generator, yet aiming to aid as much as possible in the work required to create documentation that fits the scope, in a quick painless manner.
This is not a tool to automatically generate documentation from source code.
For more advanced documentation needs, other more developed projects like Read the Docs are recommended.
The documentation you're reading was generated by Doctor.
It can be configured through some settings, and different sections of the documentation can be created, which are fully HTML compatible.
To generate the single HTML file output, the source file is passed to doctormake (NPM package):
doctormake input.xml output.html
Or manually:
node doctor.js input.xml output.html
This is meant to be a simple one-page documentation generator, yet aiming to aid as much as possible in the work required to create documentation that fits the scope, in a quick painless manner.
This is not a tool to automatically generate documentation from source code.
For more advanced documentation needs, other more developed projects like Read the Docs are recommended.
The documentation you're reading was generated by Doctor.
Doctor produces a single HTML file output, without external dependencies, which includes all JavaScript and CSS.
To do this, a file with all necessary data, which can have any name or extension, must be sent to doctormake.
Inside the input file everything is configured through XML tags, so it having an .xml or .html extension is recommended.
For example, this is how a simple input file might look like:
Then that file is sent to doctormake:
The input file path is required, however the output path is not.
If no output path is specified it will save it in the input's parent directory as "index.html".
To do this, a file with all necessary data, which can have any name or extension, must be sent to doctormake.
Inside the input file everything is configured through XML tags, so it having an .xml or .html extension is recommended.
For example, this is how a simple input file might look like:
<doc header>My Project</doc> <doc description>The introduction to my project</doc> <doc section name='What is it'> This is a section. I can use <b>Any HTML</b> here. Linebreaks are remembered, so it's easy to separate lines. I can use code samples: <xcodex> var s = "This is a code sample" if(s) { console.log("Hello Doc") } <div>This is HTML</div> </xcodex> </doc> <doc section name='Another Section'> Another part of the documentation. Every section is formatted accordingly. Every section creates an anchor link at the top and in the left menu. </doc>
Then that file is sent to doctormake:
doctormake /path/to/input/file /path/to/output/file
The input file path is required, however the output path is not.
If no output path is specified it will save it in the input's parent directory as "index.html".
Doctor is meant to be a way for others to easily read the documentation.
Sections are visually separated so it's easy to tell them apart.
There are anchor links at the top for every section:
The left menu is opened by clicking the colored edge.
It has anchor links to each section.
There is a search filter that searches section names as well as their content.
There are some keyboard events for searching and going to sections.
There's a top menu that appears when the document is scrolled.
The top menu has Prev, Top, Bottom, and Next buttons.
Prev scrolls to a previous section.
Next goes to the next section.
Top goes to the top of the document.
Bottom goes to the bottom of the document.
Some buttons become faded depending on the scroll position.
Smooth scrolling is enabled when jumping through sections.
When images are clicked they are opened in a modal window:
Section headers can be clicked, which scrolls the page to them, as well as adding a # (hash) to the URL with the proper anchor section.
There is a feedback icon when jumping to sections, next to the header.
This is to make it easy to know which section is the one you're looking for when there are multiple sections visible.
The feedback blinks for a while and disappears:
Sections are visually separated so it's easy to tell them apart.
There are anchor links at the top for every section:
The left menu is opened by clicking the colored edge.
It has anchor links to each section.
There is a search filter that searches section names as well as their content.
There are some keyboard events for searching and going to sections.
There's a top menu that appears when the document is scrolled.
The top menu has Prev, Top, Bottom, and Next buttons.
Prev scrolls to a previous section.
Next goes to the next section.
Top goes to the top of the document.
Bottom goes to the bottom of the document.
Some buttons become faded depending on the scroll position.
Smooth scrolling is enabled when jumping through sections.
When images are clicked they are opened in a modal window:
Section headers can be clicked, which scrolls the page to them, as well as adding a # (hash) to the URL with the proper anchor section.
There is a feedback icon when jumping to sections, next to the header.
This is to make it easy to know which section is the one you're looking for when there are multiple sections visible.
The feedback blinks for a while and disappears:
The <doc> tag, which is used by Doctor to build the documentation, has several types available. They all end in </doc>.
This is used to change the <title> of the document in <head>.
This is used to change the header of the documentation, the name of the project, at the very top.
The description of the project, which is shown right below the header.
The documentation's color theme can be configured.
The color specified here changes the color of the left menu, as well as the color of the links.
A light color is not recommended because it will not contrast well with the white background.
Additional CSS you might want to add can go here. This is added after the default CSS declarations, at the bottom of <head>.
Additional JavaScript you might want to add can go here. This is added after the default JavaScript declarations, at the bottom of <body>.
Path to a desired favicon. If nothing is provided it will use a default one, which is hardcoded in the output file.
Any additional declarations you might want to add at the end of <head>.
Processing is done to accept unescaped tags.
This is used to change the footer at the bottom of the documentation.
The footer's background color is the same as the theme color, with a white font.
If nothing is specified, the footer will not be rendered at all.
Processing is done to accept unescaped tags.
This can be used to enable or disable document keyboard events.
They are enabled by default. To disable them set it to false.
This doesn't remove the keyboard events for when the left menu is open.
This can be used to enable or disable image modals.
By default clicked images are opened in a modal window.
To disable that set it to false.
This is where the actual content of the documentation goes.
The name of the section appears on top, with its content below.
Sections are separated by horizontal lines.
Every section has an anchor link below the description at the top.
An anchor link to it is also added to the left menu.
Special Tags
This allows for code samples to be displayed.
Processing is done to ensure everything is displayed correctly.
It will try to autoescape tags inside <xcodex> as much as possible.
But some cases require manual escape, like unclosed <xcodex> tags.
Which shouldn't be a problem since <xcodex> is not a common tag.
<doc title>
This is used to change the <title> of the document in <head>.
<doc header>
This is used to change the header of the documentation, the name of the project, at the very top.
<doc description>
The description of the project, which is shown right below the header.
<doc theme>
The documentation's color theme can be configured.
The color specified here changes the color of the left menu, as well as the color of the links.
A light color is not recommended because it will not contrast well with the white background.
<doc style>
Additional CSS you might want to add can go here. This is added after the default CSS declarations, at the bottom of <head>.
<doc script>
Additional JavaScript you might want to add can go here. This is added after the default JavaScript declarations, at the bottom of <body>.
<doc favicon>
Path to a desired favicon. If nothing is provided it will use a default one, which is hardcoded in the output file.
<doc head>
Any additional declarations you might want to add at the end of <head>.
Processing is done to accept unescaped tags.
<doc footer>
This is used to change the footer at the bottom of the documentation.
The footer's background color is the same as the theme color, with a white font.
If nothing is specified, the footer will not be rendered at all.
Processing is done to accept unescaped tags.
<doc keyboard>
This can be used to enable or disable document keyboard events.
They are enabled by default. To disable them set it to false.
This doesn't remove the keyboard events for when the left menu is open.
<doc modal>
This can be used to enable or disable image modals.
By default clicked images are opened in a modal window.
To disable that set it to false.
<doc section name='Name Of The Section'>
This is where the actual content of the documentation goes.
The name of the section appears on top, with its content below.
Sections are separated by horizontal lines.
Every section has an anchor link below the description at the top.
An anchor link to it is also added to the left menu.
Special Tags
<xcodex> </xcodex>
This allows for code samples to be displayed.
Processing is done to ensure everything is displayed correctly.
It will try to autoescape tags inside <xcodex> as much as possible.
But some cases require manual escape, like unclosed <xcodex> tags.
Which shouldn't be a problem since <xcodex> is not a common tag.
Doctor's NPM package is called doctormake.
To use it as a command line tool do:
And then to use it:
To run it manually download a copy from the GitHub repo.
Run
And then to use it:
To use it as a command line tool do:
npm install -g doctormake
And then to use it:
doctormake input output
To run it manually download a copy from the GitHub repo.
Run
in the directory.npm install
And then to use it:
node doctor.js input output
Feedback
*
If there's a problem regarding Doctor, or you have an idea to improve it, you can try submitting an Issue in the the GitHub repo where I might respond.