Improve docs/find-missing

- automatically extend PYTHONPATH on need. The python lib is searched
  in the ../lib directory. If it's not there, add a symlink
- ignore some autodoxy symbols. Just add them in find-missing.ignore

diff --git a/docs/find-missing.ignore b/docs/find-missing.ignore
new file mode 100644 (file)
index 0000000..a996761
--- /dev/null
+++ b/docs/find-missing.ignore
@@ -0,0 +1,174 @@
+This file lists the symbols ignored in the documentation.
+It follows the RST syntact but is completely ignored by sphinx. 
+It is only used by find-missing, that will not report any definition linked here as missing.
+
+# I don't plan to document MSG in the new way.
+.. autodoxymethod:: ::MSG_barrier_destroy(const_sg_bar_t bar)
+.. autodoxymethod:: ::MSG_barrier_init(unsigned int count)
+.. autodoxymethod:: ::MSG_barrier_wait(msg_bar_t bar)
+.. autodoxymethod:: ::MSG_comm_destroy(const_msg_comm_t comm)
+.. autodoxymethod:: ::MSG_comm_get_status(const_msg_comm_t comm)
+.. autodoxymethod:: ::MSG_comm_get_task(const_msg_comm_t comm)
+.. autodoxymethod:: ::MSG_comm_test(msg_comm_t comm)
+.. autodoxymethod:: ::MSG_comm_testany(const_xbt_dynar_t comms)
+.. autodoxymethod:: ::MSG_comm_wait(msg_comm_t comm, double timeout)
+.. autodoxymethod:: ::MSG_comm_waitall(msg_comm_t *comm, int nb_elem, double timeout)
+.. autodoxymethod:: ::MSG_comm_waitany(const_xbt_dynar_t comms)
+.. autodoxymethod:: ::MSG_config(const char *key, const char *value)
+.. autodoxymethod:: ::MSG_create_environment(const char *file)
+.. autodoxymethod:: ::MSG_function_register(const char *name, xbt_main_func_t code)
+.. autodoxymethod:: ::MSG_function_register_default(xbt_main_func_t code)
+.. autodoxymethod:: ::MSG_get_clock()
+.. autodoxymethod:: ::MSG_get_host_by_name(const char *name)
+.. autodoxymethod:: ::MSG_get_host_number()
+.. autodoxymethod:: ::MSG_get_sent_msg()
+.. autodoxymethod:: ::MSG_host_by_name(const char *name)
+.. autodoxymethod:: ::MSG_host_get_attached_storage_lists(const_sg_host_t host)
+.. autodoxymethod:: ::MSG_host_get_core_number(const_sg_host_t host)
+.. autodoxymethod:: ::MSG_host_get_data(const_sg_host_t host)
+.. autodoxymethod:: ::MSG_host_get_load(const_sg_host_t host)
+.. autodoxymethod:: ::MSG_host_get_mounted_storage_list(sg_host_t host)
+.. autodoxymethod:: ::MSG_host_get_name(const_sg_host_t host)
+.. autodoxymethod:: ::MSG_host_get_nb_pstates(const_sg_host_t host)
+.. autodoxymethod:: ::MSG_host_get_power_peak_at(const_sg_host_t host, int pstate_index)
+.. autodoxymethod:: ::MSG_host_get_process_list(const_sg_host_t host, xbt_dynar_t whereto)
+.. autodoxymethod:: ::MSG_host_get_properties(const_sg_host_t host)
+.. autodoxymethod:: ::MSG_host_get_property_value(const_sg_host_t host, const char *name)
+.. autodoxymethod:: ::MSG_host_get_pstate(const_sg_host_t host)
+.. autodoxymethod:: ::MSG_host_get_speed(const_sg_host_t host)
+.. autodoxymethod:: ::MSG_host_is_on(const_sg_host_t h)
+.. autodoxymethod:: ::MSG_host_off(sg_host_t h)
+.. autodoxymethod:: ::MSG_host_on(sg_host_t h)
+.. autodoxymethod:: ::MSG_host_self()
+.. autodoxymethod:: ::MSG_host_set_data(sg_host_t host, void *data)
+.. autodoxymethod:: ::MSG_host_set_property_value(sg_host_t host, const char *name, const char *value)
+.. autodoxymethod:: ::MSG_host_set_pstate(sg_host_t host, int pstate)
+.. autodoxymethod:: ::MSG_hosts_as_dynar()
+.. autodoxymethod:: ::MSG_init_nocheck(int *argc, char **argv)
+.. autodoxymethod:: ::MSG_launch_application(const char *file)
+.. autodoxymethod:: ::MSG_mailbox_set_async(const char *alias)
+.. autodoxymethod:: ::MSG_main()
+.. autodoxymethod:: ::MSG_parallel_task_create(const char *name, int host_nb, const msg_host_t *host_list, double *flops_amount, double *bytes_amount, void *data)
+.. autodoxymethod:: ::MSG_parallel_task_execute(msg_task_t task)
+.. autodoxymethod:: ::MSG_parallel_task_execute_with_timeout(msg_task_t task, double timeout)
+.. autodoxymethod:: ::MSG_process_attach(const char *name, void *data, msg_host_t host, xbt_dict_t properties)
+.. autodoxymethod:: ::MSG_process_auto_restart_set(msg_process_t process, int auto_restart)
+.. autodoxymethod:: ::MSG_process_create(const char *name, xbt_main_func_t code, void *data, msg_host_t host)
+.. autodoxymethod:: ::MSG_process_create_with_arguments(const char *name, xbt_main_func_t code, void *data, msg_host_t host, int argc, char **argv)
+.. autodoxymethod:: ::MSG_process_create_with_environment(const char *name, xbt_main_func_t code, void *data, msg_host_t host, int argc, char **argv, xbt_dict_t properties)
+.. autodoxymethod:: ::MSG_process_daemonize(msg_process_t process)
+.. autodoxymethod:: ::MSG_process_detach()
+.. autodoxymethod:: ::MSG_process_from_PID(int pid)
+.. autodoxymethod:: ::MSG_process_get_PID(const_sg_actor_t process)
+.. autodoxymethod:: ::MSG_process_get_PPID(const_sg_actor_t process)
+.. autodoxymethod:: ::MSG_process_get_data(const_sg_actor_t process)
+.. autodoxymethod:: ::MSG_process_get_host(const_sg_actor_t process)
+.. autodoxymethod:: ::MSG_process_get_name(const_sg_actor_t process)
+.. autodoxymethod:: ::MSG_process_get_number()
+.. autodoxymethod:: ::MSG_process_get_properties(const_sg_actor_t process)
+.. autodoxymethod:: ::MSG_process_get_property_value(const_sg_actor_t process, const char *name)
+.. autodoxymethod:: ::MSG_process_is_suspended(msg_process_t process)
+.. autodoxymethod:: ::MSG_process_join(msg_process_t process, double timeout)
+.. autodoxymethod:: ::MSG_process_kill(msg_process_t process)
+.. autodoxymethod:: ::MSG_process_killall()
+.. autodoxymethod:: ::MSG_process_migrate(msg_process_t process, msg_host_t host)
+.. autodoxymethod:: ::MSG_process_on_exit(int_f_int_pvoid_t fun, void *data)
+.. autodoxymethod:: ::MSG_process_ref(const_sg_actor_t process)
+.. autodoxymethod:: ::MSG_process_restart(msg_process_t process)
+.. autodoxymethod:: ::MSG_process_resume(msg_process_t process)
+.. autodoxymethod:: ::MSG_process_self()
+.. autodoxymethod:: ::MSG_process_self_PID()
+.. autodoxymethod:: ::MSG_process_self_PPID()
+.. autodoxymethod:: ::MSG_process_self_name()
+.. autodoxymethod:: ::MSG_process_set_data(msg_process_t process, void *data)
+.. autodoxymethod:: ::MSG_process_set_data_cleanup(void_f_pvoid_t data_cleanup)
+.. autodoxymethod:: ::MSG_process_set_kill_time(msg_process_t process, double kill_time)
+.. autodoxymethod:: ::MSG_process_sleep(double nb_sec)
+.. autodoxymethod:: ::MSG_process_suspend(msg_process_t process)
+.. autodoxymethod:: ::MSG_process_unref(const_sg_actor_t process)
+.. autodoxymethod:: ::MSG_process_yield()
+.. autodoxymethod:: ::MSG_processes_as_dynar()
+.. autodoxymethod:: ::MSG_sem_acquire(msg_sem_t sem)
+.. autodoxymethod:: ::MSG_sem_acquire_timeout(msg_sem_t sem, double timeout)
+.. autodoxymethod:: ::MSG_sem_destroy(const_sg_sem_t sem)
+.. autodoxymethod:: ::MSG_sem_get_capacity(msg_sem_t sem)
+.. autodoxymethod:: ::MSG_sem_init(int initial_value)
+.. autodoxymethod:: ::MSG_sem_release(msg_sem_t sem)
+.. autodoxymethod:: ::MSG_sem_would_block(msg_sem_t sem)
+.. autodoxymethod:: ::MSG_storage_get_by_name(const char *name)
+.. autodoxymethod:: ::MSG_storage_get_data(const_sg_storage_t storage)
+.. autodoxymethod:: ::MSG_storage_get_host(const_sg_storage_t storage)
+.. autodoxymethod:: ::MSG_storage_get_name(const_sg_storage_t storage)
+.. autodoxymethod:: ::MSG_storage_get_properties(const_sg_storage_t storage)
+.. autodoxymethod:: ::MSG_storage_get_property_value(const_sg_storage_t storage, const char *name)
+.. autodoxymethod:: ::MSG_storage_read(msg_storage_t storage, sg_size_t size)
+.. autodoxymethod:: ::MSG_storage_set_data(msg_storage_t storage, void *data)
+.. autodoxymethod:: ::MSG_storage_set_property_value(msg_storage_t storage, const char *name, const char *value)
+.. autodoxymethod:: ::MSG_storage_write(msg_storage_t storage, sg_size_t size)
+.. autodoxymethod:: ::MSG_storages_as_dynar()
+.. autodoxymethod:: ::MSG_task_cancel(msg_task_t task)
+.. autodoxymethod:: ::MSG_task_create(const char *name, double flops_amount, double bytes_amount, void *data)
+.. autodoxymethod:: ::MSG_task_destroy(msg_task_t task)
+.. autodoxymethod:: ::MSG_task_dsend(msg_task_t task, const char *alias, void_f_pvoid_t cleanup)
+.. autodoxymethod:: ::MSG_task_dsend_bounded(msg_task_t task, const char *alias, void_f_pvoid_t cleanup, double maxrate)
+.. autodoxymethod:: ::MSG_task_execute(msg_task_t task)
+.. autodoxymethod:: ::MSG_task_get_bytes_amount(const_msg_task_t task)
+.. autodoxymethod:: ::MSG_task_get_category(const_msg_task_t task)
+.. autodoxymethod:: ::MSG_task_get_data(const_msg_task_t task)
+.. autodoxymethod:: ::MSG_task_get_flops_amount(const_msg_task_t task)
+.. autodoxymethod:: ::MSG_task_get_name(const_msg_task_t task)
+.. autodoxymethod:: ::MSG_task_get_remaining_communication(const_msg_task_t task)
+.. autodoxymethod:: ::MSG_task_get_remaining_work_ratio(const_msg_task_t task)
+.. autodoxymethod:: ::MSG_task_get_sender(const_msg_task_t task)
+.. autodoxymethod:: ::MSG_task_get_source(const_msg_task_t task)
+.. autodoxymethod:: ::MSG_task_irecv(msg_task_t *task, const char *alias)
+.. autodoxymethod:: ::MSG_task_irecv_bounded(msg_task_t *task, const char *alias, double rate)
+.. autodoxymethod:: ::MSG_task_isend(msg_task_t task, const char *alias)
+.. autodoxymethod:: ::MSG_task_isend_bounded(msg_task_t task, const char *alias, double maxrate)
+.. autodoxymethod:: ::MSG_task_listen(const char *alias)
+.. autodoxymethod:: ::MSG_task_listen_from(const char *alias)
+.. autodoxymethod:: ::MSG_task_receive(msg_task_t *task, const char *alias)
+.. autodoxymethod:: ::MSG_task_receive_bounded(msg_task_t *task, const char *alias, double rate)
+.. autodoxymethod:: ::MSG_task_receive_with_timeout(msg_task_t *task, const char *alias, double timeout)
+.. autodoxymethod:: ::MSG_task_receive_with_timeout_bounded(msg_task_t *task, const char *alias, double timeout, double rate)
+.. autodoxymethod:: ::MSG_task_send(msg_task_t task, const char *alias)
+.. autodoxymethod:: ::MSG_task_send_bounded(msg_task_t task, const char *alias, double rate)
+.. autodoxymethod:: ::MSG_task_send_with_timeout(msg_task_t task, const char *alias, double timeout)
+.. autodoxymethod:: ::MSG_task_send_with_timeout_bounded(msg_task_t task, const char *alias, double timeout, double maxrate)
+.. autodoxymethod:: ::MSG_task_set_bound(msg_task_t task, double bound)
+.. autodoxymethod:: ::MSG_task_set_bytes_amount(msg_task_t task, double bytes_amount)
+.. autodoxymethod:: ::MSG_task_set_category(msg_task_t task, const char *category)
+.. autodoxymethod:: ::MSG_task_set_data(msg_task_t task, void *data)
+.. autodoxymethod:: ::MSG_task_set_flops_amount(msg_task_t task, double flops_amount)
+.. autodoxymethod:: ::MSG_task_set_name(msg_task_t task, const char *name)
+.. autodoxymethod:: ::MSG_task_set_priority(msg_task_t task, double priority)
+.. autodoxymethod:: ::MSG_vm_create_core(msg_host_t pm, const char *name)
+.. autodoxymethod:: ::MSG_vm_create_multicore(msg_host_t pm, const char *name, int coreAmount)
+.. autodoxymethod:: ::MSG_vm_destroy(msg_vm_t vm)
+.. autodoxymethod:: ::MSG_vm_get_name(const_sg_vm_t vm)
+.. autodoxymethod:: ::MSG_vm_get_pm(const_sg_vm_t vm)
+.. autodoxymethod:: ::MSG_vm_get_ramsize(const_sg_vm_t vm)
+.. autodoxymethod:: ::MSG_vm_is_created(msg_vm_t vm)
+.. autodoxymethod:: ::MSG_vm_is_running(msg_vm_t vm)
+.. autodoxymethod:: ::MSG_vm_is_suspended(msg_vm_t vm)
+.. autodoxymethod:: ::MSG_vm_resume(msg_vm_t vm)
+.. autodoxymethod:: ::MSG_vm_set_bound(msg_vm_t vm, double bound)
+.. autodoxymethod:: ::MSG_vm_set_ramsize(msg_vm_t vm, size_t size)
+.. autodoxymethod:: ::MSG_vm_shutdown(msg_vm_t vm)
+.. autodoxymethod:: ::MSG_vm_start(msg_vm_t vm)
+.. autodoxymethod:: ::MSG_vm_suspend(msg_vm_t vm)
+.. autodoxymethod:: ::MSG_zone_get_by_name(const char *name)
+.. autodoxymethod:: ::MSG_zone_get_hosts(const_sg_netzone_t zone, xbt_dynar_t whereto)
+.. autodoxymethod:: ::MSG_zone_get_name(const_sg_netzone_t zone)
+.. autodoxymethod:: ::MSG_zone_get_property_value(const_sg_netzone_t zone, const char *name)
+.. autodoxymethod:: ::MSG_zone_get_root()
+.. autodoxymethod:: ::MSG_zone_get_sons(const_sg_netzone_t zone, xbt_dict_t whereto)
+.. autodoxymethod:: ::MSG_zone_set_property_value(msg_netzone_t zone, const char *name, const char *value)
+
+# These ones are a bug of Doxygen, that parse them as variables instead of types.
+# So we don't use this bogus parse result, but go directly for cpp:type directives in app_s4u.rst
+.. autodoxyvar:: ::const_sg_actor_t
+.. autodoxyvar:: ::const_sg_bar_t
+.. autodoxyvar:: ::const_sg_mutex_t
+.. autodoxyvar:: ::const_sg_sem_t
+

diff --git a/docs/find-missing.py b/docs/find-missing.py
index 2043dcc..6a79f21 100755 (executable)
--- a/docs/find-missing.py
+++ b/docs/find-missing.py
@@ -110,8 +110,17 @@ for name in python_modules:
     try:
         module = __import__(name)
     except Exception:
-        print("Cannot import {}. Did you set PYTHONPATH=../lib accordingly?".format(name))
-        sys.exit(1)
+        if os.path.exists("../lib") and "../lib" not in sys.path:
+            print("Adding ../lib to PYTHONPATH as {} cannot be imported".format(name))
+            sys.path.append("../lib")
+            try:
+                module = __import__(name)
+            except Exception:
+                print("Cannot import {}, even with PYTHONPATH=../lib".format(name))
+                sys.exit(1)
+        else:
+            print("Cannot import {}".format(name))
+            sys.exit(1)
     for sub in dir(module):
         if sub[0] == '_':
             continue
@@ -181,7 +190,7 @@ for arg in xml_files:
                 print ("member {}::{} is of kind {}".format(compoundname, name, kind))
 
 # Forget about the declarations that are done in the RST
-with os.popen('grep autodoxymethod:: source/*rst|sed \'s/^.*autodoxymethod:: //\'') as pse:
+with os.popen('grep autodoxymethod:: find-missing.ignore source/*rst|sed \'s/^.*autodoxymethod:: //\'') as pse:
     for line in (l.strip() for l in pse):
         (klass, obj, args) = (None, None, None)
         if "(" in line:
@@ -208,7 +217,7 @@ with os.popen('grep autodoxymethod:: source/*rst|sed \'s/^.*autodoxymethod:: //\
             doxy_funs[klass][obj].remove(args)
             if len(doxy_funs[klass][obj]) == 0:
                 del doxy_funs[klass][obj]
-with os.popen('grep autodoxyvar:: source/*rst|sed \'s/^.*autodoxyvar:: //\'') as pse:
+with os.popen('grep autodoxyvar:: find-missing.ignore source/*rst|sed \'s/^.*autodoxyvar:: //\'') as pse:
     for line in (l.strip() for l in pse):
         (klass, var) = line.rsplit('::', 1)