Skip to content

Commit 8e7f05a

Browse files
hazhaz
authored
Merge pull request #212 from AI-Planning/docs
Updating documentation
2 parents fcdb66d + 8324544 commit 8e7f05a

File tree

14 files changed

+123
-106
lines changed

14 files changed

+123
-106
lines changed

‎.github/workflows/docs.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ jobs:
2828
- run: pip install pdoc
2929
# ADJUST THIS: build your documentation into docs/.
3030
# We use a custom build script for pdoc itself, ideally you just run `pdoc -o docs/ ...` here.
31-
- run: pdoc macq --math -o docs
31+
- run: pdoc macq --math --docformat google -o docs
3232

3333
- uses: actions/upload-pages-artifact@v3
3434
with:

‎README.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
This library is a collection of tools for planning-like action model acquisition from state trace data. It contains a reimplementation from many existing works, and generalizes some of them to new settings.
99

10-
## Usage
10+
## Example Usage
1111

1212
```python
1313
from macq import generate, extract
@@ -21,11 +21,11 @@ traces.generate_more(10)
2121

2222
action = traces[0][0].action
2323
traces.get_usage(action)
24-
[0.05, 0.05, ..., 0.05]
24+
# [0.05, 0.05, ..., 0.05]
2525

2626
trace = traces[0]
2727
len(trace)
28-
20
28+
# 20
2929

3030
trace.fluents
3131
trace.actions
@@ -38,7 +38,7 @@ trace.get_total_cost()
3838

3939
You can find the full scope of papers considered in the survey (implemented and otherwise) at http://macq.planning.domains . This repository of model acquisition techniques will be added to over time.
4040

41-
## Survey Papers
41+
## Related Survey Papers
4242

4343
- [A Review of Machine Learning for Automated Planning](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.231.4901&rep=rep1&type=pdf) (see Fig 2)
4444
- [A Review of Learning Planning Action Models](https://hal.archives-ouvertes.fr/hal-02010536/document) (see Tbl 3)

‎docs/extract/amdn.md

Lines changed: 2 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,3 @@
1-
# AMDN
1+
### AMDN
22

3-
## Usage
4-
5-
```python
6-
from macq import generate, extract
7-
8-
print(model.details())
9-
```
10-
11-
**Output:**
12-
13-
```text
14-
15-
```
3+
Coming soon...

‎docs/extract/arms.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# ARMS
1+
### ARMS
22

3-
## Usage
3+
#### Usage
44

55
```python
66
from macq import generate, extract

‎docs/extract/extract.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
Include the argument `debug=True` to `Extract` to enable debugging for any
1010
extraction technique.
1111

12-
_Note: debugging output and interfaces are unique to each method._
12+
**Note**: debugging output and interfaces are unique to each method.
1313

1414
## Extraction Techniques
1515

@@ -19,23 +19,25 @@ _Note: debugging output and interfaces are unique to each method._
1919
- [AMDN](#amdn)
2020
- [LOCM](#locm)
2121

22-
.. include:: ../../../docs/templates/extract/observer.md
22+
----
23+
24+
.. include:: ../../docs/extract/observer.md
2325

2426
---
2527

26-
.. include:: ../../../docs/templates/extract/slaf.md
28+
.. include:: ../../docs/extract/slaf.md
2729

2830
---
2931

30-
.. include:: ../../../docs/templates/extract/arms.md
32+
.. include:: ../../docs/extract/arms.md
3133

3234
---
3335

34-
.. include:: ../../../docs/templates/extract/amdn.md
36+
.. include:: ../../docs/extract/amdn.md
3537

3638
---
3739

38-
.. include:: ../../../docs/templates/extract/locm.md
40+
.. include:: ../../docs/extract/locm.md
3941

4042
---
4143

‎docs/extract/locm.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,3 @@
1-
# LOCM
1+
### LOCM
2+
3+
Coming soon...

‎docs/extract/observer.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Observer
1+
### Observer
22

3-
## Usage
3+
#### Usage
44

55
```python
66
from macq import generate, extract

‎docs/extract/slaf.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# SLAF
1+
### SLAF
22

3-
## Usage
3+
#### Usage
44

55
```python
66
from macq import generate, extract

‎docs/index.md

Lines changed: 23 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,37 @@
1-
# Usage Documentation
1+
# General API
22

33
## Trace Generation
44

5-
- [VanillaSampling](macq/generate/pddl.html#VanillaSampling)
6-
- [RandomGoalSampling](macq/generate/pddl.html#RandomGoalSampling)
7-
- [FDRandomWalkSampling](macq/generate/pddl.html#FDRandomWalkSampling)
5+
These are the various methods implemented to generate the base trace data.
6+
7+
| Algorithm | Description |
8+
|---|---|
9+
| [VanillaSampling](macq/generate/pddl.html#VanillaSampling) | Samples actions uniformly at random |
10+
| [RandomGoalSampling](macq/generate/pddl.html#RandomGoalSampling) | Samples goals by taking a random subset of a state reached after a random walk |
11+
| [FDRandomWalkSampling](macq/generate/pddl.html#FDRandomWalkSampling) | Random walk based on a heuristic-driven depth calculation (algorithm introduced in the [FD planning system](https://www.fast-downward.org/)) |
12+
| [TraceFromGoal](macq/generate/pddl.html#TraceFromGoal) | Generates a trace from a given domain/problem (with a goal state) |
13+
| [CSV](macq/generate/csv.html) | Reads a CSV file to generate a trace |
814

915
## Tokenization
1016

11-
- [IdentityObservation](macq/observation.html#IdentityObservation)
12-
- [AtomicPartialObservation](macq/observation.html#AtomicPartialObservation)
17+
Once trace data is loaded, you can process the traces to produce lists of observations. The methods range from the identity observation (constaining the same data as original traces) to noisy and/or partially observable observations.
18+
19+
| Algorithm | Description |
20+
|---|---|
21+
| [IdentityObservation](macq/observation.html#IdentityObservation) | Unmodified versions of the input traces |
22+
| [PartialObservation](macq/observation.html#PartialObservation) | Observations with a subset of the fluents hidden in the states |
23+
| [AtomicPartialObservation](macq/observation.html#AtomicPartialObservation) | Similar to `PartialObservation`, except everything is stored as atomic strings (not fluents and parameters) |
24+
| [ActionObservation](macq/observation.html#ActionObservation) | Observations with only the actions listed (i.e., states discarded) |
25+
| [NoisyObservation](macq/observation.html#NoisyObservation) | Observations with added noise to the fluents |
26+
| [NoisyPartialObservation](macq/observation.html#NoisyPartialObservation) | Observations with added noise to the fluents and a subset of the fluents hidden in the states |
27+
| [NoisyPartialDisorderedParallelObservation](macq/observation.html#NoisyPartialDisorderedParallelObservation) | Observations with added noise to the fluents and a subset of the fluents hidden in the states, with the actions disordered and parallelized |
1328

1429
## Extraction Techniques
1530

31+
Depending on the observation type, different extraction techniques can be used to extract the relevant information from the observations. These are currently the techniques implemented:
32+
1633
- [Observer](macq/extract.html#observer)
1734
- [SLAF](macq/extract.html#slaf)
1835
- [ARMS](macq/extract.html#arms)
1936
- [AMDN](macq/extract.html#amdn)
2037
- [LOCM](macq/extract.html#locm)
21-
22-
# API Documentation

‎macq/__init__.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
11
"""
22
.. include:: ../README.md
3+
4+
----
5+
36
.. include:: ../docs/index.md
47
"""

0 commit comments

Comments
 (0)