Skip to content

Commit 5707e9f

Browse files
michaliskambimichaliskambi
committed
Better index, more concise in some places, but also add donate link, and "tutorial"
1 parent a48fa5f commit 5707e9f

4 files changed

Lines changed: 79 additions & 36 deletions

File tree

‎src/HtmlOutput.asciidoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
:doctitle: HTML Output
22

3-
Command-line option --format html (or -O html in short) makes pasdoc
3+
Command-line option `--format html` (or `-O html` in short) makes pasdoc
44
write HTML (Hypertext Markup Language) output. HTML files are usually
55
viewed using web browsers, available on all modern computer systems.
66

‎src/_includes/sidebar.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,10 @@
55

66
## Features:
77

8-
* [Writing Documentation](WritingDocumentation)
9-
108
* [Where To Place Comments](WhereToPlaceComments)
119

10+
* [Writing Documentation](WritingDocumentation)
11+
1212
* [Advanced Features](AdvancedFeatures)
1313

1414
* [Demo](PasDocAutoDoc)

‎src/_sass/pasdoc.scss‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,3 +106,11 @@
106106
.main-conten pre {
107107
overflow: scroll !important;
108108
}
109+
110+
#toc #toctitle {
111+
display: none;
112+
}
113+
#toc ul {
114+
list-style: none;
115+
padding-left: 1em;
116+
}

‎src/index.asciidoc‎

Lines changed: 68 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,104 @@
11
:doctitle: PasDoc
2+
:sectnums:
3+
:toc: left
4+
:toclevels: 4
5+
6+
## Introduction
27

38
PasDoc is a documentation tool for the Object Pascal code
4-
(as implemented by http://www.freepascal.org/[FreePascal] and
9+
(as implemented by http://www.freepascal.org/[FPC] and
510
http://www.embarcadero.com/products/delphi[Delphi]).
611
Documentation is generated from comments found in the source code
7-
and from external files.
12+
and / or in dedicated "description files". Numerous output formats are supported, including HTML, LaTeX (for PDF, PS), XML and PHP.
13+
14+
This is a _free and open source software_.
15+
//PasDoc itself is written using modern Object Pascal and can be build using FPC or Delphi.
16+
We https://castle-engine.io/donate[appreciate your donations (Michalis, maintainer of PasDoc, also makes Castle Game Engine)], esp. if you use PasDoc in a commercial project. This helps us to continue developing and improving PasDoc.
817

918
## Download
1019

1120
Download:
1221

13-
* Latest stable PasDoc release
14-
https://github.com/pasdoc/pasdoc/releases/latest[can be downloaded from here].
22+
* Latest *stable* PasDoc release https://github.com/pasdoc/pasdoc/releases/latest[can be downloaded from here].
23+
24+
* Latest *unstable* (automatic build after every commit, published once automatic tests pass) release https://github.com/pasdoc/pasdoc/releases/tag/snapshot[is available here ("snapshot" releases)].
25+
26+
You can watch our https://github.com/pasdoc/pasdoc/releases[releases page] or https://github.com/pasdoc/pasdoc/discussions/categories/announcements[announcements category in our discussions] to be notified about a new release.
27+
28+
## Tutorial
29+
30+
Put comments before the identifiers in your Pascal source code. Like this:
31+
32+
```pascal
33+
{ My amazing unit. }
34+
unit MyUnit;
35+
interface
36+
type
37+
{ My amazing class. }
38+
TMyClass = class
39+
public
40+
{ My amazing method. }
41+
procedure MyMethod;
42+
{ My amazing property. }
43+
property MyProperty: string read GetMyProperty;
44+
end;
45+
implementation
46+
...
47+
end.
48+
```
49+
50+
Process this source code with PasDoc, and get documentation in one of the output formats. From the command-line, you can do it like this:
51+
52+
```shell
53+
mkdir -p output-dir/
54+
pasdoc myunit.pas --format html --output output-dir
55+
```
56+
57+
You can also use the GUI interface, see link:PasDocGui[PasDoc GUI].
1558

16-
* Unstable (automatic build after every commit, published once automatic tests pass) releases are available at link:DevelopmentSnapshots[DevelopmentSnapshots].
59+
## Examples
1760

18-
You can watch our https://github.com/pasdoc/pasdoc/releases[releases page] to be notified about the new releases.
61+
- This is https://pasdoc.github.io/autodoc/html/index.html[PasDoc's own documentation in the HTML format].
1962
20-
## Usage
63+
- See also link:PasDocAutoDoc[PasDoc's own documentation in all the formats] .
2164
22-
See link:WhereToPlaceComments[WhereToPlaceComments],
23-
link:WritingDocumentation[WritingDocumentation] and
24-
link:SupportedTags[SupportedTags] for information on how to document
25-
your source code.
65+
- See link:ProjectsUsingPasDoc[Projects using PasDoc] for links to larger real-world
66+
examples of how documentation generated by PasDoc looks like.
2667
27-
Available output formats are
68+
## More usage information: output formats, command-line options, examples
69+
70+
For more information on how to document your source code see:
71+
72+
- link:WhereToPlaceComments[Where To Place Comments]
73+
- link:WritingDocumentation[Writing Documentation]
74+
- link:SupportedTags[Supported Tags].
75+
76+
Available output formats:
2877

2978
* link:HtmlOutput[HTML] - modern webpage documenting your project
3079
* link:HtmlHelp[HtmlHelp]
31-
* link:LatexOutput[LaTeX] - you can use this to generate PDF or PS using LaTeX tools like `pdflatex`
80+
* link:LatexOutput[LaTeX] - you can use this to generate PDF or PostScript using LaTeX tools like `pdflatex`
3281
* link:Latex2RtfOutput[Latex2rtf]
33-
* link:SimpleXmlOutput[SimpleXml] - useful to process obtained information using further tools
82+
* link:SimpleXmlOutput[SimpleXml] - useful to process obtained information using your own tools, you only need to read the generated XML file
3483
* link:PhpOutput[PHP] - PHP map from Pascal identifier -> HTML link, to implement searching/enumeration in PHP websites
3584
3685
Check out the link:CommandLine[CommandLine] to get a better feeling
37-
for how PasDoc works. There is also a GUI interface, see
38-
link:PasDocGui[PasDocGui].
39-
40-
Check out link:PasDocAutoDoc[PasDocAutoDoc] and
41-
link:ProjectsUsingPasDoc[ProjectsUsingPasDoc] to see some real-world
42-
examples of how documentation generated by PasDoc looks like, and to see
43-
some programs that use PasDoc's code.
86+
for how PasDoc works.
4487

4588
You may also be interested in the list of
4689
link:AdvancedFeatures[AdvancedFeatures] of PasDoc.
4790

4891
## Get involved
4992

50-
https://github.com/pasdoc/pasdoc/discussions[We use GitHub Team Discussions] as our forum. You're welcome to join there, everyone is welcome :)
51-
52-
You can also use the https://github.com/pasdoc/pasdoc/issues[GitHub issues] to report bugs and feature requests. If you would like to contribute, it's best to https://github.com/pasdoc/pasdoc/pulls[submit a pull request using GitHub], although you can also attach a patch file to an issue.
93+
https://github.com/pasdoc/pasdoc/discussions[We use GitHub Team Discussions] as our forum. Come and talk to us!
5394

54-
We have also collected some older "wanted features" on the link:WantedFeatures[WantedFeatures] list. And there is a link:ToDo[ToDo] list.
95+
Use the https://github.com/pasdoc/pasdoc/issues[GitHub issues] to report bugs and feature requests. If you would like to contribute, it's best to https://github.com/pasdoc/pasdoc/pulls[submit a pull request using GitHub].
5596

5697
## Development
5798

5899
See the
59-
https://github.com/pasdoc/pasdoc/blob/master/ChangeLog[ChangeLog] for
60-
recent changes to PasDoc and a short history overview.
100+
https://github.com/pasdoc/pasdoc/blob/master/ChangeLog.md[ChangeLog] for
101+
recent changes to PasDoc.
61102

62103
PasDoc source code:
63104

@@ -70,12 +111,6 @@ In short, just call
70111
----
71112
git clone https://github.com/pasdoc/pasdoc.git
72113
----
73-
+
74-
Alternatively, you can get the same code using SVN. In short, just call
75-
+
76-
----
77-
svn co https://github.com/pasdoc/pasdoc.git/trunk
78-
----
79114
* See link:CompilingPasDoc[CompilingPasDoc] for instructions how to compile PasDoc.
80115
* See link:ReleaseMaking[ReleaseMaking] to know how we test and package PasDoc for final releases.
81116

0 commit comments

Comments
 (0)